Courier Authentication API
Issue JWTs for client-side and inbox authentication.
OpenAPI Specification
openapi: 3.0.1
info:
title: Courier
description: The Courier REST API.
version: ''
paths:
/send:
post:
description: Send a message to one or more recipients.
operationId: send
tags:
- Send
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageResponse'
examples:
Example1:
value:
requestId: 1-65f240a0-47a6a120c8374de9bcf9f22a
summary: Send a message
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
message:
$ref: '#/components/schemas/Message'
description: Defines the message to be delivered
required:
- message
examples:
Example1:
summary: Send message with UserRecipient
description: Default example using UserRecipient type
value:
message:
to:
user_id: user_id
template: template_id
data:
foo: bar
Example2:
value:
message:
to:
email: [email protected]
template: template_id
data:
foo: bar
Example3:
value:
message:
to:
phone_number: '+1234567890'
template: template_id
data:
foo: bar
Example4:
value:
message:
to:
list_id: example_list
template: template_id
data:
foo: bar
Example5:
value:
message:
to:
user_id: example_user
content:
title: Hello {name}
body: How are you?
data:
name: Ben
routing:
method: single
channels:
- email
/profiles/{user_id}:
get:
description: Returns the specified user profile.
operationId: profiles_get
tags:
- User Profiles
parameters:
- name: user_id
in: path
description: A unique identifier representing the user associated with the requested profile.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileGetResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: Get a profile
security:
- BearerAuth: []
post:
description: >-
Merge the supplied values with an existing profile or create a new profile if one doesn't already
exist.
operationId: profiles_create
tags:
- User Profiles
parameters:
- name: user_id
in: path
description: A unique identifier representing the user associated with the requested profile.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MergeProfileResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: Create a profile
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
profile:
type: object
additionalProperties: true
required:
- profile
put:
description: >-
When using `PUT`, be sure to include all the key-value pairs required by the recipient's profile.
Any key-value pairs that exist in the profile but fail to be included in the `PUT` request will be
removed from the profile. Remember, a `PUT` update is a full replacement of the data. For partial
updates,
use the [Patch](https://www.courier.com/docs/reference/profiles/patch/) request.
operationId: profiles_replace
tags:
- User Profiles
parameters:
- name: user_id
in: path
description: A unique identifier representing the user associated with the requested user profile.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ReplaceProfileResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: Replace a profile
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
profile:
type: object
additionalProperties: true
required:
- profile
patch:
operationId: profiles_mergeProfile
tags:
- User Profiles
parameters:
- name: user_id
in: path
description: A unique identifier representing the user associated with the requested user profile.
required: true
schema:
type: string
responses:
'204':
description: ''
summary: Update a profile
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileUpdateRequest'
delete:
description: Deletes the specified user profile.
operationId: profiles_delete
tags:
- User Profiles
parameters:
- name: user_id
in: path
description: A unique identifier representing the user associated with the requested user profile.
required: true
schema:
type: string
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: Delete a profile
security:
- BearerAuth: []
/profiles/{user_id}/lists:
get:
description: Returns the subscribed lists for a specified user.
operationId: profiles_getListSubscriptions
tags:
- User Profiles
parameters:
- name: user_id
in: path
description: A unique identifier representing the user associated with the requested user profile.
required: true
schema:
type: string
- name: cursor
in: query
description: A unique identifier that allows for fetching the next set of message statuses.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetListSubscriptionsResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: Get list subscriptions
security:
- BearerAuth: []
post:
description: Subscribes the given user to one or more lists. If the list does not exist, it will be created.
operationId: profiles_subscribeToList
tags:
- User Profiles
parameters:
- name: user_id
in: path
description: A unique identifier representing the user associated with the requested user profile.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SubscribeToListsResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: Subscribe to one or more lists
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubscribeToListsRequest'
delete:
description: Removes all list subscriptions for given user.
operationId: profiles_deleteListSubscription
tags:
- User Profiles
parameters:
- name: user_id
in: path
description: A unique identifier representing the user associated with the requested profile.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteListSubscriptionResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: Delete list subscriptions
security:
- BearerAuth: []
/lists:
get:
description: Returns all of the lists, with the ability to filter based on a pattern.
operationId: lists_list
tags:
- Lists
parameters:
- name: cursor
in: query
description: A unique identifier that allows for fetching the next page of lists.
required: false
schema:
type: string
nullable: true
- name: pattern
in: query
description: >-
"A pattern used to filter the list items returned. Pattern types supported: exact match on
`list_id` or a pattern of one or more pattern parts. you may replace a part with either: `*` to
match all parts in that position, or `**` to signify a wildcard `endsWith` pattern match."
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ListGetAllResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: Get all lists
security:
- BearerAuth: []
/lists/{list_id}:
get:
description: Returns a list based on the list ID provided.
operationId: lists_get
tags:
- Lists
parameters:
- name: list_id
in: path
description: A unique identifier representing the list you wish to retrieve.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionList'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
summary: Get a list
security:
- BearerAuth: []
put:
description: Create or replace an existing list with the supplied values.
operationId: lists_update
tags:
- Lists
parameters:
- name: list_id
in: path
description: A unique identifier representing the list you wish to retrieve.
required: true
schema:
type: string
responses:
'204':
description: ''
summary: Update a list
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListPutParams'
delete:
description: Delete a list by list ID.
operationId: lists_delete
tags:
- Lists
parameters:
- name: list_id
in: path
description: A unique identifier representing the list you wish to retrieve.
required: true
schema:
type: string
responses:
'204':
description: ''
summary: Delete a list
security:
- BearerAuth: []
/lists/{list_id}/restore:
put:
description: Restore a previously deleted list.
operationId: lists_restore
tags:
- Lists
parameters:
- name: list_id
in: path
description: A unique identifier representing the list you wish to retrieve.
required: true
schema:
type: string
responses:
'204':
description: ''
summary: Restore a list
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
/lists/{list_id}/subscriptions:
get:
description: Get the list's subscriptions.
operationId: lists_getSubscribers
tags:
- Lists
parameters:
- name: list_id
in: path
description: A unique identifier representing the list you wish to retrieve.
required: true
schema:
type: string
- name: cursor
in: query
description: A unique identifier that allows for fetching the next set of list subscriptions
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ListGetSubscriptionsResponse'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
summary: Get the subscriptions for a list
security:
- BearerAuth: []
post:
description: >-
Subscribes additional users to the list, without modifying existing subscriptions. If the list does
not exist, it will be automatically created.
operationId: lists_addSubscribers
tags:
- Lists
parameters:
- name: list_id
in: path
description: A unique identifier representing the list you wish to retrieve.
required: true
schema:
type: string
responses:
'202':
description: ''
'204':
description: ''
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: Add subscribers to a list
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
recipients:
type: array
items:
$ref: '#/components/schemas/PutSubscriptionsRecipient'
required:
- recipients
put:
description: >-
Subscribes the users to the list, overwriting existing subscriptions. If the list does not exist, it
will be automatically created.
operationId: lists_updateSubscribers
tags:
- Lists
parameters:
- name: list_id
in: path
description: A unique identifier representing the list you wish to retrieve.
required: true
schema:
type: string
responses:
'202':
description: ''
'204':
description: ''
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: Subscribe users to a list
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
recipients:
type: array
items:
$ref: '#/components/schemas/PutSubscriptionsRecipient'
required:
- recipients
/lists/{list_id}/subscriptions/{user_id}:
put:
description: >-
Subscribe a user to an existing list (note: if the List does not exist, it will be automatically
created).
operationId: lists_subscribe
tags:
- Lists
parameters:
- name: list_id
in: path
description: A unique identifier representing the list you wish to retrieve.
required: true
schema:
type: string
- name: user_id
in: path
description: A unique identifier representing the recipient associated with the list
required: true
schema:
type: string
responses:
'204':
description: ''
summary: Subscribe a single user profile to a list
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
preferences:
$ref: '#/components/schemas/RecipientPreferences'
nullable: true
delete:
description: Delete a subscription to a list by list ID and user ID.
operationId: lists_unsubscribe
tags:
- Lists
parameters:
- name: list_id
in: path
description: A unique identifier representing the list you wish to retrieve.
required: true
schema:
type: string
- name: user_id
in: path
description: A unique identifier representing the recipient associated with the list
required: true
schema:
type: string
responses:
'204':
description: ''
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
summary: Unsubscribe a user profile from a list
security:
- BearerAuth: []
/audiences/{audience_id}:
get:
description: Returns the specified audience by id.
operationId: audiences_get
tags:
- Audiences
parameters:
- name: audience_id
in: path
description: A unique identifier representing the audience_id
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Audience'
summary: Get an audience
security:
- BearerAuth: []
put:
description: Creates or updates audience.
operationId: audiences_update
tags:
- Audiences
parameters:
- name: audience_id
in: path
description: A unique identifier representing the audience id
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AudienceUpdateResponse'
summary: Update an audience
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
nullable: true
description: The name of the audience
description:
type: string
nullable: true
description: A description of the audience
operator:
$ref: '#/components/schemas/LogicalOperator'
nullable: true
description: The logical operator (AND/OR) for the top-level filter
filter:
$ref: '#/components/schemas/AudienceFilterConfig'
nullable: true
delete:
description: Deletes the specified audience.
operationId: audiences_delete
tags:
- Audiences
parameters:
- name: audience_id
in: path
description: A unique identifier representing the audience id
required: true
schema:
type: string
responses:
'204':
description: ''
summary: Delete an audience
security:
- BearerAuth: []
/audiences/{audience_id}/members:
get:
description: Get list of members of an audience.
operationId: audiences_listMembers
tags:
- Audiences
parameters:
- name: audience_id
in: path
description: A unique identifier representing the audience id
required: true
schema:
type: string
- name: cursor
in: query
description: A unique identifier that allows for fetching the next set of members
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AudienceMemberListResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: List audience members
security:
- BearerAuth: []
/audiences:
get:
description: Get the audiences associated with the authorization token.
operationId: audiences_listAudiences
tags:
- Audiences
parameters:
- name: cursor
in: query
description: A unique identifier that allows for fetching the next set of audiences
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AudienceListResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: List all audiences
security:
- BearerAuth: []
/messages:
get:
description: Fetch the statuses of messages you've previously sent.
operationId: messages_list
tags:
- Sent Messages
parameters:
- name: archived
in: query
description: A boolean value that indicates whether archived messages should be included in the response.
required: false
schema:
type: boolean
nullable: true
- name: cursor
in: query
description: A unique identifier that allows for fetching the next set of messages.
required: false
schema:
type: string
nullable: true
- name: event
in: query
description: A unique identifier representing the event that was used to send the event.
required: false
schema:
type: string
nullable: true
- name: list
in: query
description: A unique identifier representing the list the message was sent to.
required: false
schema:
type: string
nullable: true
- name: messageId
in: query
description: A unique identifier representing the message_id returned from either /send or /send/list.
required: false
schema:
type: string
nullable: true
- name: notification
in: query
description: A unique identifier representing the notification that was used to send the event.
required: false
schema:
type: string
nullable: true
- name: provider
in: query
description: >-
The key assocated to the provider you want to filter on. E.g., sendgrid, inbox, twilio, slack,
msteams, etc. Allows multiple values to be set in query parameters.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: recipient
in: query
description: A unique identifier representing the recipient associated with the requested profile.
required: false
schema:
type: string
nullable: true
- name: status
in: query
description: >-
An indicator of the current status of the message. Allows multiple values to be set in query
parameters.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: tag
in: query
description: >-
A tag placed in the metadata.tags during a notification send. Allows multiple values to be set in
query parameters.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: tags
in: query
description: >-
A comma delimited list of 'tags'. Messages will be returned if they match any of the tags passed
in.
required: false
schema:
type: string
nullable: true
- name: tenant_id
in: query
description: Messages sent with the context of a Tenant
required: false
schema:
type: string
nullable: true
- name: enqueued_after
in: query
description: The enqueued datetime of a message to filter out messages received before.
required: false
schema:
type: string
nullable: true
- name: traceId
in: query
description: The unique identifier used to trace the requests
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ListMessagesResponse'
summary: List messages
security:
- BearerAuth: []
/messages/{message_id}:
get:
description: Fetch the status of a message you've previously sent.
operationId: messages_get
tags:
- Sent Messages
parameters:
- name: message_id
in: path
description: A unique identifier associated with the message you wish to retrieve (results from a send).
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MessageDetailsExtended'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MessageNotFound'
summary: Get message
security:
- BearerAuth: []
/messages/{message_id}/cancel:
post:
description: >-
Cancel a message that is currently in the process of being delivered. A well-formatted API call to the
cancel message API will return either `200` status code for a successful cancellation or `409` status
code for an unsuccessful cancellation. Both cases will include the actual message record in the
response body (see details below).
operationId: messages_cancel
tags:
- Sent Messages
parameters:
- name: message_id
in: path
description: A unique identifier representing the message ID
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MessageDetails'
summary: Cancel message
security:
- BearerAuth: []
/messages/{message_id}/history:
get:
description: Fetch the array of events of a message you've previously sent.
operationId: messages_getHistory
tags:
- Sent Messages
parameters:
- name: message_id
in: path
description: A unique identifier representing the message ID
required: true
schema:
type: string
- name: type
in: query
description: A supported Message History type that will filter the events returned.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MessageHistoryResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MessageNotFound'
summary: Get message history
security:
- BearerAuth: []
/messages/{message_id}/output:
get:
operationId: messages_getContent
tags:
- Sent Messages
parameters:
- name: message_id
in: path
description: A unique identifier associated with the message you wish to retrieve (results from a send).
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/RenderOutputResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MessageNotFound'
summary: Get message content
security:
- BearerAuth: []
/requests/{request_id}/archive:
put:
operationId: messages_archive
tags:
-
# --- truncated at 32 KB (272 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/courier/refs/heads/main/openapi/courier-openapi.yml