Store and manage recipient profiles keyed by your user id - create, get, replace, merge/patch, and delete a profile, and list the subscription lists a user belongs to. Profiles hold channel addresses (email, phone, tokens) and custom data used at send time.
openapi: 3.0.3
info:
title: Courier API
description: >-
Courier is notification infrastructure that orchestrates transactional and
product messaging across email, SMS, push, chat, and an in-app inbox from a
single REST API. This document models the primary public endpoints under the
base URL https://api.courier.com: sending notifications (Send), inspecting
sent messages, managing lists, user profiles, preferences, device tokens,
notification templates, brands, automations, audiences, tenants, bulk jobs,
audit events, and translations. All requests are authenticated with a Bearer
API key. Endpoint paths are grounded in Courier's published API reference;
request and response bodies are modeled and simplified.
version: '2024-01'
contact:
name: Courier
url: https://www.courier.com
x-endpoint-confidence: >-
Paths and methods are grounded in the Courier API reference
(https://www.courier.com/docs/reference). Schemas are modeled, not exhaustive.
servers:
- url: https://api.courier.com
description: Courier production API
security:
- bearerAuth: []
tags:
- name: Send
description: Dispatch a notification across channels.
- name: Messages
description: Inspect, track, cancel, and archive sent messages.
- name: Lists
description: Subscription lists and their subscribers.
- name: User Profiles
description: Recipient profiles keyed by your user id.
- name: User Preferences
description: Per-user, per-topic notification preferences.
- name: Device Tokens
description: Push notification device tokens for a user.
- name: Notification Templates
description: Notification templates designed in the Courier studio.
- name: Brands
description: Reusable logos, colors, and email styling.
- name: Automations
description: Multi-step notification workflows.
- name: Audiences
description: Dynamic audiences defined by profile filters.
- name: Tenants
description: Organizations/accounts for multi-tenant apps.
- name: Bulk
description: One-to-many sends via jobs.
- name: Audit Events
description: Workspace audit events.
- name: Translations
description: Localization strings per domain and locale.
paths:
/send:
post:
operationId: sendMessage
tags: [Send]
summary: Send a message
description: >-
Dispatches a single notification to one or more recipients, routed across
channels using a template or inline content, per-recipient routing, data,
and overrides. Returns a requestId used to track the resulting messages.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendRequest'
responses:
'202':
description: The send request was accepted for processing.
content:
application/json:
schema:
type: object
properties:
requestId:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/messages:
get:
operationId: listMessages
tags: [Messages]
summary: List messages
description: Fetch the statuses of messages you have previously sent.
parameters:
- name: cursor
in: query
schema: { type: string }
- name: status
in: query
schema: { type: string }
- name: recipient
in: query
schema: { type: string }
responses:
'200':
description: A paged list of messages.
content:
application/json:
schema:
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
results:
type: array
items:
$ref: '#/components/schemas/Message'
'401':
$ref: '#/components/responses/Unauthorized'
/messages/{message_id}:
parameters:
- $ref: '#/components/parameters/MessageId'
get:
operationId: getMessage
tags: [Messages]
summary: Get a message
description: Retrieve the status of a single message by id.
responses:
'200':
description: The requested message.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/messages/{message_id}/content:
parameters:
- $ref: '#/components/parameters/MessageId'
get:
operationId: getMessageContent
tags: [Messages]
summary: Get message content
description: Retrieve the rendered content of a message as delivered to each channel.
responses:
'200':
description: The rendered message content.
content:
application/json:
schema:
type: object
additionalProperties: true
'401':
$ref: '#/components/responses/Unauthorized'
/messages/{message_id}/history:
parameters:
- $ref: '#/components/parameters/MessageId'
get:
operationId: getMessageHistory
tags: [Messages]
summary: Get message history
description: >-
Retrieve the delivery and engagement history for a message (ENQUEUED,
SENT, DELIVERED, OPENED, CLICKED, UNDELIVERABLE, etc.).
responses:
'200':
description: The message history events.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
type: object
additionalProperties: true
'401':
$ref: '#/components/responses/Unauthorized'
/messages/{message_id}/cancel:
parameters:
- $ref: '#/components/parameters/MessageId'
post:
operationId: cancelMessage
tags: [Messages]
summary: Cancel a message
description: Cancel a message that is currently enqueued and not yet delivered.
responses:
'200':
description: The cancelled message.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/messages/{message_id}/archive:
parameters:
- $ref: '#/components/parameters/MessageId'
put:
operationId: archiveMessage
tags: [Messages]
summary: Archive a message
description: Archive a message so it no longer appears in the default message list.
responses:
'204':
description: The message was archived.
'401':
$ref: '#/components/responses/Unauthorized'
/lists:
get:
operationId: listLists
tags: [Lists]
summary: Get all lists
description: Returns all subscription lists in the workspace, paginated.
parameters:
- name: cursor
in: query
schema: { type: string }
responses:
'200':
description: A paged list of lists.
content:
application/json:
schema:
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
items:
type: array
items:
$ref: '#/components/schemas/List'
'401':
$ref: '#/components/responses/Unauthorized'
/lists/{list_id}:
parameters:
- $ref: '#/components/parameters/ListId'
get:
operationId: getList
tags: [Lists]
summary: Get a list
responses:
'200':
description: The requested list.
content:
application/json:
schema:
$ref: '#/components/schemas/List'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: putList
tags: [Lists]
summary: Create or replace a list
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListInput'
responses:
'200':
description: The created or replaced list.
content:
application/json:
schema:
$ref: '#/components/schemas/List'
delete:
operationId: deleteList
tags: [Lists]
summary: Delete a list
responses:
'204':
description: The list was deleted.
/lists/{list_id}/restore:
parameters:
- $ref: '#/components/parameters/ListId'
put:
operationId: restoreList
tags: [Lists]
summary: Restore a deleted list
responses:
'204':
description: The list was restored.
/lists/{list_id}/subscriptions:
parameters:
- $ref: '#/components/parameters/ListId'
get:
operationId: getListSubscriptions
tags: [Lists]
summary: Get list subscriptions
responses:
'200':
description: The users subscribed to the list.
content:
application/json:
schema:
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
items:
type: array
items:
type: object
additionalProperties: true
put:
operationId: subscribeUsersToList
tags: [Lists]
summary: Subscribe multiple users to a list
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
recipients:
type: array
items:
type: object
additionalProperties: true
responses:
'204':
description: The users were subscribed.
/lists/{list_id}/subscriptions/{user_id}:
parameters:
- $ref: '#/components/parameters/ListId'
- $ref: '#/components/parameters/UserId'
put:
operationId: subscribeUserToList
tags: [Lists]
summary: Subscribe a user to a list
responses:
'204':
description: The user was subscribed.
delete:
operationId: unsubscribeUserFromList
tags: [Lists]
summary: Unsubscribe a user from a list
responses:
'204':
description: The user was unsubscribed.
/profiles/{user_id}:
parameters:
- $ref: '#/components/parameters/UserId'
get:
operationId: getProfile
tags: [User Profiles]
summary: Get a profile
responses:
'200':
description: The requested profile.
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createProfile
tags: [User Profiles]
summary: Create or merge a profile
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileInput'
responses:
'200':
description: The created profile.
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
put:
operationId: replaceProfile
tags: [User Profiles]
summary: Replace a profile
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileInput'
responses:
'200':
description: The replaced profile.
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
patch:
operationId: patchProfile
tags: [User Profiles]
summary: Merge/patch a profile
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
patch:
type: array
items:
type: object
additionalProperties: true
responses:
'200':
description: The patched profile.
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
delete:
operationId: deleteProfile
tags: [User Profiles]
summary: Delete a profile
responses:
'204':
description: The profile was deleted.
/profiles/{user_id}/lists:
parameters:
- $ref: '#/components/parameters/UserId'
get:
operationId: getProfileLists
tags: [User Profiles]
summary: Get the lists a user is subscribed to
responses:
'200':
description: The subscription lists for the user.
content:
application/json:
schema:
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
results:
type: array
items:
$ref: '#/components/schemas/List'
/users/{user_id}/preferences:
parameters:
- $ref: '#/components/parameters/UserId'
get:
operationId: listUserPreferences
tags: [User Preferences]
summary: List user preferences
description: List a user's notification preferences across subscription topics.
responses:
'200':
description: The user's topic preferences.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/TopicPreference'
/users/{user_id}/preferences/{topic_id}:
parameters:
- $ref: '#/components/parameters/UserId'
- name: topic_id
in: path
required: true
schema: { type: string }
get:
operationId: getUserTopicPreference
tags: [User Preferences]
summary: Get a user topic preference
responses:
'200':
description: The user's preference for the topic.
content:
application/json:
schema:
$ref: '#/components/schemas/TopicPreference'
put:
operationId: updateUserTopicPreference
tags: [User Preferences]
summary: Update a user topic preference
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TopicPreference'
responses:
'204':
description: The preference was updated.
/users/{user_id}/tokens:
parameters:
- $ref: '#/components/parameters/UserId'
get:
operationId: listUserTokens
tags: [Device Tokens]
summary: List a user's device tokens
responses:
'200':
description: The user's device tokens.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DeviceToken'
/users/{user_id}/tokens/{token}:
parameters:
- $ref: '#/components/parameters/UserId'
- name: token
in: path
required: true
schema: { type: string }
get:
operationId: getUserToken
tags: [Device Tokens]
summary: Get a device token
responses:
'200':
description: The device token.
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceToken'
put:
operationId: putUserToken
tags: [Device Tokens]
summary: Add or update a device token
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceToken'
responses:
'204':
description: The token was stored.
patch:
operationId: patchUserToken
tags: [Device Tokens]
summary: Patch a device token
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'204':
description: The token was patched.
delete:
operationId: deleteUserToken
tags: [Device Tokens]
summary: Delete a device token
responses:
'204':
description: The token was deleted.
/notifications:
get:
operationId: listNotifications
tags: [Notification Templates]
summary: List notification templates
responses:
'200':
description: A paged list of notification templates.
content:
application/json:
schema:
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
results:
type: array
items:
$ref: '#/components/schemas/Notification'
/notifications/{notification_id}/content:
parameters:
- name: notification_id
in: path
required: true
schema: { type: string }
get:
operationId: getNotificationContent
tags: [Notification Templates]
summary: Get notification content
responses:
'200':
description: The template content blocks.
content:
application/json:
schema:
type: object
additionalProperties: true
post:
operationId: updateNotificationContent
tags: [Notification Templates]
summary: Update notification content
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'204':
description: The content was updated.
/notifications/{notification_id}/draft/submit:
parameters:
- name: notification_id
in: path
required: true
schema: { type: string }
put:
operationId: submitNotificationDraft
tags: [Notification Templates]
summary: Submit a notification draft for publishing
responses:
'204':
description: The draft was submitted.
/brands:
get:
operationId: listBrands
tags: [Brands]
summary: List brands
responses:
'200':
description: A paged list of brands.
content:
application/json:
schema:
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
results:
type: array
items:
$ref: '#/components/schemas/Brand'
post:
operationId: createBrand
tags: [Brands]
summary: Create a brand
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BrandInput'
responses:
'200':
description: The created brand.
content:
application/json:
schema:
$ref: '#/components/schemas/Brand'
/brands/{brand_id}:
parameters:
- name: brand_id
in: path
required: true
schema: { type: string }
get:
operationId: getBrand
tags: [Brands]
summary: Get a brand
responses:
'200':
description: The requested brand.
content:
application/json:
schema:
$ref: '#/components/schemas/Brand'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: replaceBrand
tags: [Brands]
summary: Replace a brand
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BrandInput'
responses:
'200':
description: The replaced brand.
content:
application/json:
schema:
$ref: '#/components/schemas/Brand'
delete:
operationId: deleteBrand
tags: [Brands]
summary: Delete a brand
responses:
'204':
description: The brand was deleted.
/automations/invoke:
post:
operationId: invokeAdHocAutomation
tags: [Automations]
summary: Invoke an ad-hoc automation
description: Invoke an automation run defined inline in the request body.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
automation:
type: object
additionalProperties: true
brand:
type: string
data:
type: object
additionalProperties: true
profile:
type: object
additionalProperties: true
recipient:
type: string
template:
type: string
responses:
'202':
description: The automation run was accepted.
content:
application/json:
schema:
type: object
properties:
runId:
type: string
/automations/{template_id}/invoke:
parameters:
- name: template_id
in: path
required: true
schema: { type: string }
post:
operationId: invokeAutomationTemplate
tags: [Automations]
summary: Invoke an automation template
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'202':
description: The automation template run was accepted.
content:
application/json:
schema:
type: object
properties:
runId:
type: string
/audiences:
get:
operationId: listAudiences
tags: [Audiences]
summary: List audiences
responses:
'200':
description: A paged list of audiences.
content:
application/json:
schema:
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
items:
type: array
items:
$ref: '#/components/schemas/Audience'
/audiences/{audience_id}:
parameters:
- name: audience_id
in: path
required: true
schema: { type: string }
get:
operationId: getAudience
tags: [Audiences]
summary: Get an audience
responses:
'200':
description: The requested audience.
content:
application/json:
schema:
$ref: '#/components/schemas/Audience'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: putAudience
tags: [Audiences]
summary: Create or update an audience
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AudienceInput'
responses:
'200':
description: The created or updated audience.
content:
application/json:
schema:
$ref: '#/components/schemas/Audience'
delete:
operationId: deleteAudience
tags: [Audiences]
summary: Delete an audience
responses:
'204':
description: The audience was deleted.
/audiences/{audience_id}/members:
parameters:
- name: audience_id
in: path
required: true
schema: { type: string }
get:
operationId: listAudienceMembers
tags: [Audiences]
summary: List audience members
responses:
'200':
description: The members currently matching the audience.
content:
application/json:
schema:
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
items:
type: array
items:
type: object
additionalProperties: true
/tenants:
get:
operationId: listTenants
tags: [Tenants]
summary: List tenants
responses:
'200':
description: A paged list of tenants.
content:
application/json:
schema:
type: object
properties:
has_more:
type: boolean
items:
type: array
items:
$ref: '#/components/schemas/Tenant'
/tenants/{tenant_id}:
parameters:
- name: tenant_id
in: path
required: true
schema: { type: string }
get:
operationId: getTenant
tags: [Tenants]
summary: Get a tenant
responses:
'200':
description: The requested tenant.
content:
application/json:
schema:
$ref: '#/components/schemas/Tenant'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: putTenant
tags: [Tenants]
summary: Create or replace a tenant
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TenantInput'
responses:
'200':
description: The created or replaced tenant.
content:
application/json:
schema:
$ref: '#/components/schemas/Tenant'
delete:
operationId: deleteTenant
tags: [Tenants]
summary: Delete a tenant
responses:
'204':
description: The tenant was deleted.
/tenants/{tenant_id}/users:
parameters:
- name: tenant_id
in: path
required: true
schema: { type: string }
get:
operationId: listTenantUsers
tags: [Tenants]
summary: List users in a tenant
responses:
'200':
description: The users associated with the tenant.
content:
application/json:
schema:
type: object
properties:
has_more:
type: boolean
items:
type: array
items:
type: object
additionalProperties: true
/bulk:
post:
operationId: createBulkJob
tags: [Bulk]
summary: Create a bulk job
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
message:
$ref: '#/components/schemas/InboundBulkMessage'
responses:
'200':
description: The created bulk job.
content:
application/json:
schema:
type: object
properties:
jobId:
type: string
/bulk/{job_id}:
parameters:
- $ref: '#/components/parameters/JobId'
get:
operationId: getBulkJob
tags: [Bulk]
summary: Get a bulk job
responses:
'200':
description: The bulk job status.
content:
application/json:
schema:
type: object
additionalProperties: true
post:
operationId: addUsersToBulkJob
tags: [Bulk]
summary: Add users to a bulk job
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
users:
type: array
items:
type: object
additionalProperties: true
responses:
'204':
description: The users were added.
/bulk/{job_id}/run:
parameters:
- $ref: '#/components/parameters/JobId'
post:
operationId: runBulkJob
tags: [Bulk]
summary: Run a bulk job
responses:
'202':
description: The bulk job started running.
/bulk/{job_id}/users:
parameters:
- $ref: '#/components/parameters/JobId'
get:
operationId: listBulkJobUsers
tags: [Bulk]
summary: List users in a bulk job
responses:
'200':
description: The users in the bulk job.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
additionalProperties: true
/audit-events:
get:
operationId: listAuditEvents
tags: [Audit Events]
summary: List audit events
responses:
'200':
description: A paged list of audit events.
content:
application/json:
schema:
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
results:
type: array
items:
$ref: '#/components/schemas/AuditEvent'
/audit-events/{audit_event_id}:
parameters:
- name: audit_event_id
in: path
required: true
schema: { type: string }
get:
operationId: getAuditEvent
tags: [Audit Events]
summary: Get an audit event
responses:
'200':
description: The requested audit event.
content:
application/json:
schema:
$ref: '#/components/schemas/AuditEvent'
'404':
$ref: '#/components/responses/NotFound'
/translations/{domain}/{locale}:
parameters:
- name: domain
in: path
required: true
schema: { type: string }
- name: locale
in: path
required: true
schema: { type: string }
get:
operationId: getTranslation
tags: [Translations]
summary: Get translations for a locale
description: Retrieve the translation (.po) content for a domain and locale.
responses:
'200':
description: The translation content.
content:
text/plain:
schema:
type: string
put:
operationId: updateTranslation
tags: [Translations]
summary: Update translations for a locale
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'204':
description: The translation was updated.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Courier API key passed as `Authorization: Bearer <YOUR_API_KEY>`. Keys
are found in the Courier settings under API Keys and are environment
scoped (test vs production).
parameters:
MessageId:
name: message_id
in: path
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/courier-com/refs/heads/main/openapi/courier-com-openapi.yml