Apple Push Notifications Service (APNS)

Setup

Go to your Apple Developer Account
Click “Certificates”
Click “Keys”
Click the ”+” button
Name the Key
Click “Enable” on “Apple Push Notifications Service (APNs)”
Click “Continue”
Click “Register”
Click “Download”
Go to the APNS Provider Configuration
Enter the required information
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 SDK	APNS Token Management	Tracking Analytics
iOS	Automatic	Automatic
Android	Not Supported	Not Supported
React Native	Automatic	Automatic
Flutter	Automatic	Automatic

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 request you can make to the send API. It shows two APNS provider overrides:

providers.apn.override.body.payload adds custom data at the payload root, alongside the reserved aps dictionary. Your app reads these keys to do things like open a specific screen when the user taps the notification.
providers.apn.override.body.sound and providers.apn.override.body.badge set iOS-specific values. Courier compiles the aps dictionary for you from the message content and these overrides.

Other supported providers.apn.override.body fields include alert, sound, badge, payload, expiry (a Unix timestamp that defaults to 1 hour after the send), topic, category, threadId, content-available, apns-priority, and apns-collapse-id.

Setting providers.apn.override.body.aps replaces the entire compiled aps dictionary, including the rendered alert. If you set aps directly, re-supply alert, sound, and badge yourself, or the notification arrives with no title or body. Prefer the individual overrides above so Courier keeps building the aps dictionary for you.

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.

Sending to a `user_id` (Recommended)

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": {
						"sound": "ping.aiff",
						"badge": 99,
						"payload": {
							"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": {
						"sound": "ping.aiff",
						"badge": 99,
						"payload": {
							"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": {
						"sound": "ping.aiff",
						"badge": 99,
						"payload": {
							"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.

Invalid device tokens

When APNs rejects a token, Courier records the outcome so future sends can skip tokens that will never succeed. This status tracking applies to managed tokens (tokens synced by a Courier Mobile SDK). Tokens you pass directly via apn.token or apn.tokens are used as sent and are not status-tracked.

APNs rejection reasons BadDeviceToken, Unregistered, DeviceTokenNotForTopic, and MissingDeviceToken mark that specific token as failed for that user. The token is skipped on later sends until the device registers a fresh one.
This status is scoped to the individual token and user. It does not affect other users, other tokens, or other channels.
Managed tokens that have not been refreshed in 60 days are treated as stale and are not used. Courier Mobile SDKs refresh tokens on app launch, so keeping the SDK integrated avoids staleness.

If a user stops receiving push notifications, confirm their device has registered a current token (reinstalling the app generates a new one) and that your app calls the Courier SDK’s token registration on every launch.

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:

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
“Attach Mutable Content” supports Courier’s iOS Notification Service Extension for better push notification delivery tracking.

​Setup

​Profile Requirements

​Getting APNS Tokens

​With a Courier Mobile SDK

​Without a Courier Mobile SDK

​Sending Messages

​ClickAction and Data Mapping

​Sending to a user_id (Recommended)

​Silent Messages

​Sending to a token

​Sending to multiple tokens

​Troubleshooting

​BadDeviceToken

​BadEnvironmentKeyInToken

​Invalid device tokens

​Automatic Courier Mobile SDK Formatting

Setup

Profile Requirements

Getting APNS Tokens

With a Courier Mobile SDK

Without a Courier Mobile SDK

Sending Messages

ClickAction and Data Mapping

Sending to a `user_id` (Recommended)

Silent Messages

Sending to a `token`

Sending to multiple `tokens`

Troubleshooting

`BadDeviceToken`

`BadEnvironmentKeyInToken`

Invalid device tokens

Automatic Courier Mobile SDK Formatting