Send or schedule a notification

Create a campaign for one of four audiences: device_ids, external_ids, all devices, or a saved audience (audience_id). Sending runs asynchronously. Use Idempotency-Key for retries and dedup_key to reject duplicate business notifications for 30 days.

Authorization

ApiKey

AuthorizationBearer <token>

An API key, sent as Authorization: Bearer carillon_sk_live_…. A secret key sends, reads traces and manages devices; a mobile key may only register its own device and report that device’s events.

In: header

Header Parameters

idempotency-key?string

Retry key retained for 24 hours. Reuse the same key and identical request-body bytes to receive the original response. A different body returns 422; a concurrent request returns 409.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

audience*|||

payload*

dedup_key?string

Business deduplication key. Reuse returns 409 for 30 days regardless of the body. Use Idempotency-Key for request retries.

Length1 <= length <= 255

send_at?string

Scheduled send time, shared by all recipients. Must be in the future and within 30 days. Returns status scheduled.

Formatdate-time

local_time?string

Recipient-local send time in HH:MM format. Sends today if that time has not passed in the device timezone, otherwise tomorrow. Requires timezone_fallback.

Match^([01]\d|2[0-3]):[0-5]\d$

timezone_fallback?string

IANA timezone for devices without a known timezone, such as Europe/Paris. Required with local_time.

Length1 <= length <= 64

delivery_rate?integer

Campaign-wide notifications per second. Defaults to the app limit; values above that limit return 422. Applies across all timezone waves, which span about 26 hours.

Range1 <= value <= 1000000

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/v1/messages" \  -H "Content-Type: application/json" \  -d '{    "audience": {      "device_ids": [        "743d709b-361e-4f32-8914-0bf36add9bdd"      ]    },    "payload": {}  }'

{  "audience": {    "kind": "device_ids",    "size": 0  },  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "sending",  "mode": "live",  "created_at": "2019-08-24T14:15:22Z",  "deliveries": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940"    }  ],  "warnings": [    {      "code": "no_valid_credential",      "platform": "ios",      "detail": "string",      "devices": 0,      "reason": "string",      "credential": {        "key_id": "string",        "rejected_at": "2019-08-24T14:15:22Z"      }    }  ]}

Send or schedule a notification

Authorization

Header Parameters

Request Body

Response Body

202application/json

402application/problem+json

403application/problem+json

409application/problem+json

413application/problem+json

422application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`