Skip to main content

​
Setup

  1. Go to your Apple Developer Account
  2. Click “Certificates”
  3. Click “Keys”
  4. Click the ”+” button
  5. Name the Key
  6. Click “Enable” on “Apple Push Notifications Service (APNs)”
  7. Click “Continue”
  8. Click “Register”
  9. Click “Download”
  10. Go to the APNS Provider Configuration
  11. Enter the required information
  12. Click “Install Provider” or “Save”

​
Profile Requirements

APNS requires device tokens. You can provide them directly via apn.token or apn.tokens in the recipient profile, or use a Courier Mobile SDK which syncs tokens automatically and lets you send to a user_id instead.

​
Getting APNS Tokens

​
With a Courier Mobile SDK

Using a Courier Mobile SDK is the best way to set this up. All Courier Mobile SDKs sync APNS tokens to Courier and will be automatically managed. This allows you to send pushes directly to a user_id rather than APNS tokens.
Mobile SDKAPNS Token ManagementTracking Analytics
iOSAutomaticAutomatic
AndroidNot SupportedNot Supported
React NativeAutomaticAutomatic
FlutterAutomaticAutomatic

​
Without a Courier Mobile SDK

Follow Apple’s Documentation to setup push notifications on your iOS device. What APNS tokens look like: 
469d754f85604fa6bcf98c4299ba9aa760a5a3b01c5ca7277342cf3fbcea5c91
You will need to sync, store, and manage your user’s APNS tokens. This likely will require you to create entries in your database, deploy separate endpoints, and add extra development time that can be avoided with a Courier Mobile SDK.If you’d like Courier delivery and click tracking, you will also need to manually make a request to the trackingUrl.

​
Sending Messages

This is a common example request you can make to the send api that shows:
  1. providers.apn.override.body.aps.YOUR_CUSTOM_KEY for adding custom data to your payload. This is usually used for opening a specific screen in your app when the user takes action on a push notification.
  2. providers.apn.override.body.aps for applying iOS specific values. You can learn more about these here.

​
ClickAction and Data Mapping

To pass a click action link into your push notification, enable the data mapping toggle in the Push channel settings.
You can then perform a send request that looks similar to this, passing the clickAction in the data payload. 
{
    "message": {
        "to": {
            "user_id": "mike_mill_made_it"
        },
        "template": "HY59FFJQTR4JGEGT25HQD2D201GK",
        "data": {
            "click_action": "https://courier.com"
        }
    }
}
Sounds and badges can only be configured in the override schema of a send request at this time, and are not compatible with a template field attached. If your push notifications require sounds and badges, shape your push request with sound and badge in the override as shown below.
curl --request POST \
  --url https://api.courier.com/send \
  --header 'Authorization: Bearer YOUR_AUTH_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
	"message": {
		"to": {
			"user_id": "YOUR_USER_ID"
		},
		"content": {
			"title": "Hey there 👋",
			"body": "Have a great day 😁"
		},
		"routing": {
			"method": "all",
			"channels": [
				"apn"
			]
		},
		"providers": {
			"apn": {
				"override": {
					"body": {
						"aps": {
							"alert": {
								"title": "Hey there 👋",
								"body": "Have a great day 😁"
							},
							"sound": "ping.aiff",
							"badge": 99,
							"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
						}
					}
				}
			}
		}
	}
}'

​
Silent Messages

curl --request POST \
  --url https://api.courier.com/send \
  --header 'Authorization: Bearer YOUR_AUTH_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
	"message": {
		"to": {
			"user_id": "YOUR_USER_ID"
		},
		"content": {
			"title": "...",
			"body": "..."
		},
		"routing": {
			"method": "all",
			"channels": [
				"apn"
			]
		},
		"providers": {
			"apn": {
				"override": {
					"silent": true,
					"body": {
						"badge": 123
					}
				}
			}
		}
	}
}'

​
Sending to a token

curl --request POST \
  --url https://api.courier.com/send \
  --header 'Authorization: Bearer YOUR_AUTH_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
	"message": {
		"to": {
			"apn": {
				"token": "YOUR_APNS_TOKEN"
			}
		},
		"content": {
			"title": "Hey there 👋",
			"body": "Have a great day 😁"
		},
		"routing": {
			"method": "all",
			"channels": [
				"apn"
			]
		},
		"providers": {
			"apn": {
				"override": {
					"body": {
						"aps": {
							"alert": {
								"title": "Hey there 👋",
								"body": "Have a great day 😁"
							},
							"sound": "ping.aiff",
							"badge": 99,
							"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
						}
					}
				}
			}
		}
	}
}'

​
Sending to multiple tokens

curl --request POST \
  --url https://api.courier.com/send \
  --header 'Authorization: Bearer YOUR_AUTH_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
	"message": {
		"to": {
			"apn": {
				"tokens": ["APNS_TOKEN_ONE", "APNS_TOKEN_TWO"]
			}
		},
		"content": {
			"title": "Hey there 👋",
			"body": "Have a great day 😁"
		},
		"routing": {
			"method": "all",
			"channels": [
				"apn"
			]
		},
		"providers": {
			"apn": {
				"override": {
					"body": {
						"aps": {
							"alert": {
								"title": "Hey there 👋",
								"body": "Have a great day 😁"
							},
							"sound": "ping.aiff",
							"badge": 99,
							"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
						}
					}
				}
			}
		}
	}
}'
To send to specific devices when a user has multiple APNS tokens, see Targeting Specific Devices.

​
Troubleshooting

​
BadDeviceToken

APNs returns BadDeviceToken when the token you sent does not match any registered device for the environment (production vs. sandbox) you are targeting. Common causes:
  • Wrong environment: A token registered against the sandbox environment will fail in production and vice versa. Check the environment toggle in APNS channel settings.
  • Stale token: The user uninstalled and reinstalled the app, generating a new token. Update the stored token via the Device Tokens API when your app receives a new registration token.
  • Token never registered: The token was never added to a Courier user profile. Ensure your app calls the registration step on every launch.

​
BadEnvironmentKeyInToken

The key you used to sign the APNs JWT belongs to a different team or bundle ID than the token. Verify that the Team ID and Key ID in your Courier APNS configuration match the app whose tokens you are sending.

​
Token status cascade (14-day lockout)

When APNs marks a device token as invalid — due to a failed send, a wrong-environment send, or the user disabling push — that status is global across all providers. Any subsequent send attempt through any APNs integration using the same token will fail for up to 14 days, even if you switch providers or channels.
One failed send through a misconfigured APNS environment can poison the token globally for 14 days. If you see sudden spikes in BadDeviceToken errors after a configuration change, audit your environment setting first. Tokens that hit this state must be refreshed from the device.

​
Automatic Courier Mobile SDK Formatting

By default, Courier automatically formats parts of the APNS payload to make a better developer experience for you if you are working with a Courier Mobile SDK. Here you can manage the automatic APNS settings.
What this setting does:
  1. Creates a simple toggle to send to Apple’s production or sandbox push notification environment. Production (switch is on) is used in your production app and Sandbox (switch is off) is used for testing and development. More Details
  2. “Attach Mutable Content” supports Courier’s iOS Notification Service Extension for better push notification delivery tracking.