Skip to main content
This section documents every Courier REST API endpoint with request/response schemas, code examples, and authentication details.

​
API Keys

To call the Courier API, you need an API key. Grab one from the Courier dashboard, then pass it as a Bearer token: 
Authorization: Bearer <YOUR_API_KEY>

​
SDKs

Courier’s server SDKs wrap the REST API with typed methods for sending notifications, managing users, configuring channels, and more. Install the SDK for your language to get started. 
npm install @trycourier/courier
Courier also offers mobile SDKs (iOS, Android, Flutter, React Native) and client-side browser SDKs. See the SDKs overview for the full list.

​
Rate Limiting

EndpointOperationLimit
Lists APIPOST to subscriptions20 requests/minute
PUT to lists20 requests/minute
Events APIPUT to events20 requests/minute
Brands APIPUT to brands200 requests/minute

​
Payload Limits

The maximum request body size for all Courier API endpoints is 6 MB. Requests that exceed this limit are rejected with a 413 Payload Too Large response. Base64-encoded content (common for email attachments) inflates size by roughly 33%; a 4.5 MB raw file will approach the limit after encoding. For large files, host them externally (S3, GCS, or your own CDN) and pass download URLs to your notification via data variables.
Payload limits cap the size of a single API request. For limits on how many messages you can send to a user or workspace, see Send Limits.

​
Idempotency

Add an Idempotency-Key header to any POST request to ensure it runs only once, even if retried.
cURL
curl --request POST \
  --url https://api.courier.com/send \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <YOUR_UNIQUE_KEY>' \
  --data '{
    "message": {
      "to": { "user_id": "user-123" },
      "template": "WELCOME_TEMPLATE",
      "data": { "name": "Alice" }
    }
  }'
  • Use a unique value (like a UUID) for each logical request.
  • Replaying the same key returns the original response, even if it was an error.
  • Keys expire after 24 hours.

​
Next Steps

Send a message

Create a user profile

Create a JWT

Update a list