openapi: 3.0.1 info: title: Courier description: The Courier REST API for sending and managing notifications across channels. 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-67f340b1-58b7b231d9485ef0cda0a38b 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: user@example.com 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' examples: Example: value: profile: {} preferences: categories: categories_key: status: OPTED_IN rules: - start: string until: string channel_preferences: - channel: direct_message notifications: notifications_key: status: OPTED_IN rules: - start: string until: string channel_preferences: - channel: direct_message '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: status: SUCCESS '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: status: SUCCESS '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true results: - id: example.list.id name: Example List created: '2024-01-15T10:30:00.000Z' updated: '2024-01-15T10:30:00.000Z' preferences: categories: categories_key: status: OPTED_IN rules: - start: string until: string channel_preferences: - channel: direct_message notifications: notifications_key: status: OPTED_IN rules: - start: string until: string channel_preferences: - channel: direct_message '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: status: SUCCESS '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: status: SUCCESS '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true items: - id: example.list.id name: Example List created: '2024-01-15T10:30:00.000Z' updated: '2024-01-15T10:30:00.000Z' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: id: example.list.id name: Example List created: '2024-01-15T10:30:00.000Z' updated: '2024-01-15T10:30:00.000Z' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true items: - recipientId: abc-123 created: '2024-01-15T10:30:00.000Z' preferences: categories: categories_key: status: OPTED_IN rules: - start: string until: string channel_preferences: - channel: direct_message notifications: notifications_key: status: OPTED_IN rules: - start: string until: string channel_preferences: - channel: direct_message '404': description: '' content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: id: aud_01H8M... name: Example Name description: An example description. operator: AND filter: operator: AND filters: - operator: EQ path: profile.title value: Software Engineer - operator: IS_AFTER path: profile.created_at value: '2024-01-01' created_at: '2024-01-15T10:30:00.000Z' updated_at: '2024-01-15T10:30:00.000Z' 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' examples: Example: value: audience: id: aud_01H8M... name: Example Name description: An example description. operator: AND filter: operator: AND filters: - operator: EQ path: profile.title value: Software Engineer - operator: IS_AFTER path: profile.created_at value: '2024-01-01' created_at: '2024-01-15T10:30:00.000Z' updated_at: '2024-01-15T10:30:00.000Z' 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) combining the top-level `filter.filters`. Convenience alias for `filter.operator`: if set, it is applied to the top-level filter group. Prefer setting `operator` directly inside `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' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true items: - added_at: '2024-01-15T10:30:00.000Z' audience_id: aud_123 audience_version: 1 member_id: abc-123 reason: string '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true items: - id: aud_01H8M... name: Example Name description: An example description. operator: AND filter: operator: AND filters: - operator: EQ path: profile.title value: Software Engineer - operator: IS_AFTER path: profile.created_at value: '2024-01-01' created_at: '2024-01-15T10:30:00.000Z' updated_at: '2024-01-15T10:30:00.000Z' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true results: - id: 1-5e2b2615-05efbb3acab9172f88dd3f6f status: CANCELED enqueued: 1 sent: 1 delivered: 1 opened: 1 clicked: 1 recipient: string event: string notification: string error: string reason: BOUNCED 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' examples: Example: value: id: 1-5e2b2615-05efbb3acab9172f88dd3f6f status: CANCELED enqueued: 1 sent: 1 delivered: 1 opened: 1 clicked: 1 recipient: string event: string notification: string error: string reason: BOUNCED providers: - {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: '' content: application/json: schema: $ref: '#/components/schemas/MessageNotFound' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: id: 1-5e2b2615-05efbb3acab9172f88dd3f6f status: CANCELED enqueued: 1 sent: 1 delivered: 1 opened: 1 clicked: 1 recipient: string event: string notification: string error: string reason: BOUNCED summary: Cancel message security: - BearerAuth: [] /messages/{message_id}/resend: post: description: >- Resend a previously sent message. The original send request is loaded from storage and a brand-new send is enqueued for the same recipient and content, producing a **new** `messageId` — the original message is not modified. Throttled by a per-message rate limit; a repeat inside the limit window returns `429 Too Many Requests`. operationId: messages_resend tags: - Sent Messages parameters: - name: message_id in: path description: A unique identifier representing the message ID of the original message to resend. required: true schema: type: string responses: '202': description: >- The resend request was accepted. A brand-new send has been enqueued and its `messageId` is returned in the response body. content: application/json: schema: $ref: '#/components/schemas/ResendMessageResponse' examples: Example: value: messageId: 1-5e2b2615-05efbb3acab9172f88dd3f6f '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Message with ID is not supported for resend. type: invalid_request_error '404': description: '' content: application/json: schema: $ref: '#/components/schemas/MessageNotFound' examples: Example: value: message: Example message text type: invalid_request_error '429': description: '' content: application/json: schema: $ref: '#/components/schemas/TooManyRequests' examples: Example: value: message: Too Many Requests type: rate_limit_error summary: Resend 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' examples: Example: value: results: - {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: '' content: application/json: schema: $ref: '#/components/schemas/MessageNotFound' examples: Example: value: message: Example message text type: invalid_request_error 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' examples: Example: value: results: - channel: string channel_id: abc-123 content: html: string title: Example Name body: string subject: string text: string blocks: - type: string text: string '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: '' content: application/json: schema: $ref: '#/components/schemas/MessageNotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Get message content security: - BearerAuth: [] /requests/{request_id}/archive: put: operationId: messages_archive tags: - Sent Messages parameters: - name: request_id in: path description: A unique identifier representing the request ID required: true schema: type: string responses: '204': description: '' summary: Archive message security: - BearerAuth: [] /notifications: get: description: List notification templates in your workspace. operationId: notifications_list tags: - Notification Templates parameters: - name: cursor in: query description: Opaque pagination cursor from a previous response. Omit for the first page. required: false schema: type: string nullable: true - name: notes in: query description: Include template notes in the response. Only applies to legacy templates. required: false schema: type: boolean nullable: true - name: event_id in: query description: Filter to templates linked to this event map ID. required: false schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/NotificationListResponse' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true results: - created_at: 1 updated_at: 1 id: nt_01kx4h2jdafq8bk9aftxak4b40 routing: method: all channels: - string tags: data: - id: abc-123 name: Example Name title: Example Name topic_id: pt_01kx4h2jdafq8bk99mj9q2gsa2 note: string event_ids: - string summary: List Notification Templates security: - BearerAuth: [] post: description: >- Create a notification template. Requires all fields in the notification object. Templates are created in draft state by default. operationId: notifications_create tags: - Notification Templates parameters: [] responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/NotificationTemplateResponse' examples: DraftCreated: value: id: nt_01kx4h2jdafq8bk9aftxak4b40 name: Welcome Email tags: - onboarding - welcome brand: id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag subscription: topic_id: pt_01kx4h2jdafq8bk9a26x0kvd1t routing: strategy_id: rs_01kx4h2jdafq8bk9amzvy6hbv0 content: version: '2022-01-01' elements: - type: channel channel: email elements: - type: meta title: Welcome! - type: text content: Hello {{data.name}}. state: DRAFT created: 1710000000000 creator: user_abc updated: 1710000000000 updater: user_abc '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: ValidationError: value: type: invalid_request_error message: 'notification.name: Required; notification.content: Required' RoutingStrategyNotFound: value: type: invalid_request_error message: Routing strategy rs_01kx4kepxgfq9ty3rersxgwk8x not found summary: Create Notification Template security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotificationTemplateCreateRequest' examples: DraftWithAllFields: summary: Create a draft template with all fields populated value: notification: name: Welcome Email tags: - onboarding - welcome brand: id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag subscription: topic_id: pt_01kx4h2jdafq8bk9a26x0kvd1t routing: strategy_id: rs_01kx4h2jdafq8bk9amzvy6hbv0 content: version: '2022-01-01' elements: - type: channel channel: email elements: - type: meta title: Welcome! - type: text content: Hello {{data.name}}. state: DRAFT MinimalDraft: summary: Create a minimal draft template value: notification: name: Bare Minimum tags: [] brand: null subscription: null routing: null content: version: '2022-01-01' elements: [] AutoPublish: summary: Create and immediately publish value: notification: name: Auto-Published Template tags: - alerts brand: null subscription: null routing: null content: version: '2022-01-01' elements: - type: channel channel: email elements: - type: meta title: Alert - type: text content: You have a new alert. state: PUBLISHED /notifications/{id}: get: description: >- Retrieve a notification template by ID. Returns the published version by default. Pass version=draft to retrieve an unpublished template. operationId: notifications_retrieve tags: - Notification Templates parameters: - name: id in: path description: Template ID (nt_ prefix). required: true schema: type: string - name: version in: query description: >- Version to retrieve. One of "draft", "published", or a version string like "v001". Defaults to "published". required: false schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/NotificationTemplateResponse' examples: PublishedTemplate: value: id: nt_01kx4h2jdafq8bk9aftxak4b40 name: Welcome Email tags: - onboarding brand: id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag subscription: topic_id: pt_01kx4h2jdafq8bk9a26x0kvd1t routing: null content: version: '2022-01-01' elements: - type: channel channel: email elements: - type: meta title: Welcome! - type: text content: Hello {{data.name}}. state: PUBLISHED created: 1710000000000 creator: user_abc updated: 1710000001000 updater: user_def '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: TemplateNotFound: value: type: invalid_request_error message: Notification template nt_01kx4kepxgfq9ty3r3wyf61n5t not found summary: Get Notification Template security: - BearerAuth: [] put: description: Replace a notification template. All fields are required. operationId: notifications_replace tags: - Notification Templates parameters: - name: id in: path description: Template ID (nt_ prefix). required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/NotificationTemplateResponse' examples: Replaced: value: id: nt_01kx4h2jdafq8bk9aftxak4b40 name: Updated Name tags: - updated brand: null subscription: null routing: null content: version: '2022-01-01' elements: - type: channel channel: email elements: - type: meta title: Updated - type: text content: Updated content. state: PUBLISHED created: 1710000000000 creator: user_abc updated: 1710000001000 updater: user_def '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: ValidationError: value: type: invalid_request_error message: 'notification.name: Required; notification.content: Required' RoutingStrategyNotFound: value: type: invalid_request_error message: Routing strategy rs_01kx4kepxgfq9ty3rersxgwk8x not found '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: TemplateNotFound: value: type: invalid_request_error message: Notification template nt_01kx4kepxgfq9ty3r3wyf61n5t not found summary: Replace Notification Template security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotificationTemplateUpdateRequest' examples: FullReplace: summary: Replace all fields value: notification: name: Updated Name tags: - updated brand: null subscription: null routing: null content: version: '2022-01-01' elements: - type: channel channel: email elements: - type: meta title: Updated - type: text content: Updated content. state: PUBLISHED delete: description: Archive a notification template. operationId: notifications_archive tags: - Notification Templates parameters: - name: id in: path description: Template ID (nt_ prefix). required: true schema: type: string responses: '204': description: Successfully archived. '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: TemplateNotFound: value: type: invalid_request_error message: Notification template nt_01kx4kepxgfq9ty3r3wyf61n5t not found summary: Archive Notification Template security: - BearerAuth: [] /notifications/{id}/versions: get: description: List versions of a notification template. operationId: notifications_listVersions tags: - Notification Templates parameters: - name: id in: path description: Template ID (nt_ prefix). required: true schema: type: string - name: cursor in: query description: Opaque pagination cursor from a previous response. Omit for the first page. required: false schema: type: string - name: limit in: query description: Maximum number of versions to return per page. Default 10, max 10. required: false schema: type: integer default: 10 maximum: 10 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/NotificationTemplateVersionListResponse' examples: VersionHistory: value: versions: - version: draft created: 1774037925522 creator: user_abc has_changes: true - version: published:v003 created: 1774037924446 creator: user_abc - version: v002 created: 1774037923967 creator: user_def - version: v001 created: 1774037922000 creator: user_def paging: cursor: null more: false '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: InvalidCursor: value: type: invalid_request_error message: Invalid cursor format '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: TemplateNotFound: value: type: invalid_request_error message: Notification template nt_01kx4kepxgfq9ty3r3wyf61n5t not found summary: List Notification Template Versions security: - BearerAuth: [] /notifications/{id}/publish: post: description: >- Publish a notification template. Publishes the current draft by default. Pass a version in the request body to publish a specific historical version. operationId: notifications_publish tags: - Notification Templates parameters: - name: id in: path description: Template ID (nt_ prefix). required: true schema: type: string responses: '204': description: Successfully published, or already published with no changes (idempotent). '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: InvalidVersion: value: type: invalid_request_error message: 'version: Expected format: v001, v002, etc.' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: TemplateNotFound: value: type: invalid_request_error message: Notification template nt_01kx4kepxgfq9ty3r3wyf61n5t not found VersionNotFound: value: type: invalid_request_error message: Version not found for template nt_01kx4h2jdafq8bk9aftxak4b40 summary: Publish Notification Template security: - BearerAuth: [] requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/NotificationTemplatePublishRequest' examples: PublishDraft: summary: Publish the current draft (default) value: {} PublishSpecificVersion: summary: Publish a specific historical version (rollback) value: version: v001 /notifications/{id}/duplicate: post: description: >- Duplicate a notification template. Creates a standalone copy within the same workspace and environment, with " COPY" appended to the title. The copy clones the source draft's tags, brand, subscription topic, routing strategy, channels, and content, and is always created as a standalone template (it is not linked to any journey or broadcast, even if the source was). Templates that are scoped to a journey or a broadcast cannot be duplicated through this endpoint. operationId: notifications_duplicate tags: - Notification Templates parameters: - name: id in: path description: Template ID (nt_ prefix). required: true schema: type: string responses: '201': description: The newly created template copy. content: application/json: schema: $ref: '#/components/schemas/NotificationTemplateResponse' examples: DuplicatedTemplate: value: id: nt_01kx4m9ntsfk6vny0k8crygtc5 name: Welcome Email COPY tags: - onboarding brand: id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag subscription: topic_id: pt_01kx4h2jdafq8bk9a26x0kvd1t routing: null content: version: '2022-01-01' elements: - type: channel channel: email elements: - type: meta title: Welcome! - type: text content: Hello {{data.name}}. state: DRAFT created: 1710000000000 creator: user_abc updated: 1710000000000 updater: user_abc '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: TemplateNotFound: value: type: invalid_request_error message: Notification template nt_01kx4kepxgfq9ty3r3wyf61n5t not found '422': description: >- Unprocessable Entity - the template is scoped to a journey or a broadcast and cannot be duplicated through this endpoint. content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: JourneyScoped: value: type: invalid_request_error message: >- Template nt_01kx4h2jdafq8bk9aftxak4b40 is scoped to journey jry_01kx4m9ntrfk6vnxzww2rbpfd1. Use /journeys/jry_01kx4m9ntrfk6vnxzww2rbpfd1/notifications/nt_01kx4h2jdafq8bk9aftxak4b40 to manage it. summary: Duplicate Notification Template security: - BearerAuth: [] /notifications/{id}/content: get: description: >- Retrieve the content of a notification template. The response shape depends on whether the template uses V1 (blocks/channels) or V2 (elemental) content. Use the `version` query parameter to select draft, published, or a specific historical version. operationId: notifications_getContent tags: - Notification Templates parameters: - name: id in: path description: Notification template ID (`nt_` prefix). required: true schema: type: string - name: version in: query description: Accepts `draft`, `published`, or a version string (e.g., `v001`). Defaults to `published`. required: false schema: type: string examples: published: value: published summary: Current published version (default) draft: value: draft summary: Current draft version historical: value: v001 summary: Specific historical version responses: '200': description: Template content retrieved. content: application/json: schema: oneOf: - $ref: '#/components/schemas/NotificationContentGetResponse' - $ref: '#/components/schemas/NotificationGetContentResponse' examples: V2Content: summary: V2 elemental content response value: version: '2022-01-01' elements: - id: elem_channel_1 type: channel checksum: abc123def456 locales: es: checksum: es_abc123 fr: checksum: fr_abc123 elements: - id: elem_meta_1 type: meta checksum: meta_abc123 - id: elem_text_1 type: text checksum: text_abc123 V1Content: summary: V1 blocks/channels content response (legacy) value: blocks: - id: block_1 type: text content: Hello channels: - id: channel_1 type: email checksum: legacy_checksum '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: TemplateNotFound: value: type: invalid_request_error message: Notification template nt_01kx4kepxgfq9ty3r3wyf61n5t not found summary: Get Notification Content security: - BearerAuth: [] put: description: >- Replace the elemental content of a notification template. Overwrites all elements in the template with the provided content. Only supported for V2 (elemental) templates. operationId: notifications_putContent tags: - Notification Templates parameters: - name: id in: path description: Notification template ID (`nt_` prefix). required: true schema: type: string responses: '200': description: Content replaced. content: application/json: schema: $ref: '#/components/schemas/NotificationContentMutationResponse' examples: ContentUpdated: summary: Content replaced successfully value: id: nt_01kx4h2jdafq8bk9aftxak4b40 version: '2022-01-01' elements: - id: elem_1 checksum: abc123 - id: elem_2 checksum: def456 state: DRAFT '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: ValidationError: value: type: invalid_request_error message: 'content: Required' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: TemplateNotFound: value: type: invalid_request_error message: Notification template nt_01kx4kepxgfq9ty3r3wyf61n5t not found summary: Put Notification Content security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotificationContentPutRequest' examples: ReplaceContent: summary: Replace all content elements value: content: version: '2022-01-01' elements: - type: channel channel: email elements: - type: meta title: Welcome! - type: text content: Hello {{data.name}}. state: DRAFT /notifications/{id}/elements/{elementId}: put: description: Update a single element within a notification template. Only supported for V2 (elemental) templates. operationId: notifications_putElement tags: - Notification Templates parameters: - name: id in: path description: Notification template ID (`nt_` prefix). required: true schema: type: string - name: elementId in: path description: Element ID within the template. required: true schema: type: string responses: '200': description: Element updated. content: application/json: schema: $ref: '#/components/schemas/NotificationContentMutationResponse' examples: ElementUpdated: summary: Element updated successfully value: id: nt_01kx4h2jdafq8bk9aftxak4b40 version: '2022-01-01' elements: - id: elem_1 checksum: abc123 - id: elem_2 checksum: def456 state: DRAFT '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: ValidationError: value: type: invalid_request_error message: 'type: Required' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: TemplateNotFound: value: type: invalid_request_error message: Notification template nt_01kx4kepxgfq9ty3r3wyf61n5t not found ElementNotFound: value: type: invalid_request_error message: Element elem_nonexistent not found in template nt_01kx4h2jdafq8bk9aftxak4b40 summary: Put Notification Element security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotificationElementPutRequest' examples: UpdateTextElement: summary: Update a text element value: type: text data: content: Updated text content state: DRAFT /notifications/{id}/locales/{localeId}: put: description: >- Set locale-specific content overrides for a notification template. Each element override must reference an existing element by ID. Only supported for V2 (elemental) templates. operationId: notifications_putLocale tags: - Notification Templates parameters: - name: id in: path description: Notification template ID (`nt_` prefix). required: true schema: type: string - name: localeId in: path description: Locale code (e.g., `es`, `fr`, `pt-BR`). required: true schema: type: string responses: '200': description: Locale overrides applied. content: application/json: schema: $ref: '#/components/schemas/NotificationContentMutationResponse' examples: LocaleUpdated: summary: Locale content set successfully value: id: nt_01kx4h2jdafq8bk9aftxak4b40 version: '2022-01-01' elements: - id: elem_1 checksum: abc123 - id: elem_2 checksum: def456 state: DRAFT '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: ValidationError: value: type: invalid_request_error message: 'elements: Required' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: TemplateNotFound: value: type: invalid_request_error message: Notification template nt_01kx4kepxgfq9ty3r3wyf61n5t not found summary: Put Notification Locale security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotificationLocalePutRequest' examples: SetSpanishLocale: summary: Set Spanish locale overrides value: elements: - id: elem_1 content: Hola {{data.name}}. - id: elem_2 title: Bienvenido! state: DRAFT /notifications/{id}/{submissionId}/checks: get: description: Retrieve the submission checks for a notification template. operationId: notifications_getSubmissionChecks tags: - Notification Templates parameters: - name: id in: path description: Notification template ID. required: true schema: type: string - name: submissionId in: path description: Submission ID. required: true schema: type: string responses: '200': description: Submission checks retrieved. content: application/json: schema: $ref: '#/components/schemas/SubmissionChecksGetResponse' examples: Example: value: checks: - id: abc-123 status: RESOLVED type: custom updated: 1 summary: Get Submission Checks security: - BearerAuth: [] put: description: Replace the submission checks for a notification template. operationId: notifications_replaceSubmissionChecks tags: - Notification Templates parameters: - name: id in: path description: Notification template ID. required: true schema: type: string - name: submissionId in: path description: Submission ID. required: true schema: type: string responses: '200': description: Submission checks replaced. content: application/json: schema: $ref: '#/components/schemas/SubmissionChecksReplaceResponse' examples: Example: value: checks: - id: abc-123 status: RESOLVED type: custom updated: 1 summary: Replace Submission Checks security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: checks: type: array items: $ref: '#/components/schemas/BaseCheck' required: - checks delete: description: Cancel a submission for a notification template. operationId: notifications_cancelSubmission tags: - Notification Templates parameters: - name: id in: path description: Notification template ID. required: true schema: type: string - name: submissionId in: path description: Submission ID. required: true schema: type: string responses: '204': description: Submission cancelled. summary: Cancel Submission security: - BearerAuth: [] /auth/issue-token: post: description: Returns a new access token. operationId: authTokens_issueToken tags: - Authentication parameters: [] responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/IssueTokenResponse' examples: Example: value: token: string summary: Create a JWT security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: scope: type: string description: >- Available scopes: - `user_id:` - Defines which user the token will be scoped to. Multiple can be listed if needed. Ex `user_id:pigeon user_id:bluebird`. - `read:messages` - Read messages. - `read:user-tokens` - Read user push tokens. - `write:user-tokens` - Write user push tokens. - `read:brands[:]` - Read brands, optionally restricted to a specific brand_id. Examples `read:brands`, `read:brands:my_brand`. - `write:brands[:]` - Write brands, optionally restricted to a specific brand_id. Examples `write:brands`, `write:brands:my_brand`. - `inbox:read:messages` - Read inbox messages. - `inbox:write:events` - Write inbox events, such as mark message as read. - `read:preferences` - Read user preferences. - `write:preferences` - Write user preferences. Example: `user_id:user123 write:user-tokens inbox:read:messages inbox:write:events read:preferences write:preferences read:brands` expires_in: type: string description: |- Duration for token expiration. Accepts various time formats: - "2 hours" - 2 hours from now - "1d" - 1 day - "3 days" - 3 days - "10h" - 10 hours - "2.5 hrs" - 2.5 hours - "1m" - 1 minute - "5s" - 5 seconds - "1y" - 1 year required: - scope - expires_in examples: InboxExample: value: scope: >- user_id:$YOUR_USER_ID write:user-tokens inbox:read:messages inbox:write:events read:preferences write:preferences read:brands expires_in: $YOUR_NUMBER days /tenants/{tenant_id}: get: operationId: tenants_get tags: - Tenants parameters: - name: tenant_id in: path description: A unique identifier representing the tenant to be returned. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Tenant' examples: Example: value: id: tenant_abc name: Example Name parent_tenant_id: tenant_abc default_preferences: items: - status: OPTED_OUT has_custom_routing: true custom_routing: - direct_message id: pt_01kx4h2jdafq8bk99mj9q2gsa2 properties: {} user_profile: {} brand_id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Get a Tenant security: - BearerAuth: [] put: operationId: tenants_createOrReplace tags: - Tenants parameters: - name: tenant_id in: path description: A unique identifier representing the tenant to be returned. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Tenant' examples: Example: value: id: tenant_abc name: Example Name parent_tenant_id: tenant_abc default_preferences: items: - status: OPTED_OUT has_custom_routing: true custom_routing: - direct_message id: pt_01kx4h2jdafq8bk99mj9q2gsa2 properties: {} user_profile: {} brand_id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Create or Replace a Tenant security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Name of the tenant. parent_tenant_id: type: string nullable: true description: Tenant's parent id (if any). default_preferences: $ref: '#/components/schemas/DefaultPreferences' nullable: true description: Defines the preferences used for the tenant when the user hasn't specified their own. properties: type: object additionalProperties: true nullable: true description: Arbitrary properties accessible to a template. user_profile: type: object additionalProperties: true nullable: true description: A user profile object merged with user profile on send. brand_id: type: string nullable: true description: Brand to be used for the account when one is not specified by the send call. required: - name delete: operationId: tenants_delete tags: - Tenants parameters: - name: tenant_id in: path description: Id of the tenant to be deleted. required: true schema: type: string responses: '204': description: '' summary: Delete a Tenant security: - BearerAuth: [] /tenants: get: operationId: tenants_list tags: - Tenants parameters: - name: parent_tenant_id in: query description: Filter the list of tenants by parent_id required: false schema: type: string nullable: true - name: limit in: query description: |- The number of tenants to return (defaults to 20, maximum value of 100) required: false schema: type: integer nullable: true - name: cursor in: query description: Continue the pagination with the next cursor required: false schema: type: string nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/TenantListResponse' examples: Example: value: cursor: MTpFWUNFRkRRN0c1WERTRTU2 has_more: true items: - id: tenant_abc name: Example Name parent_tenant_id: tenant_abc default_preferences: items: - status: OPTED_OUT has_custom_routing: true custom_routing: - direct_message id: pt_01kx4h2jdafq8bk99mj9q2gsa2 properties: {} user_profile: {} brand_id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag next_url: https://example.com url: https://example.com type: list summary: Get a List of Tenants security: - BearerAuth: [] /tenants/{tenant_id}/users: get: operationId: tenants_getUsersByTenant tags: - Tenants parameters: - name: tenant_id in: path description: Id of the tenant for user membership. required: true schema: type: string - name: limit in: query description: |- The number of accounts to return (defaults to 20, maximum value of 100) required: false schema: type: integer nullable: true - name: cursor in: query description: Continue the pagination with the next cursor required: false schema: type: string nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ListUsersForTenantResponse' examples: Example: value: items: - user_id: user_123 type: user tenant_id: tenant_abc profile: {} has_more: true url: https://example.com next_url: https://example.com cursor: MTpFWUNFRkRRN0c1WERTRTU2 type: list '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Get Users in Tenant security: - BearerAuth: [] /tenants/{tenant_id}/default_preferences/items/{topic_id}: put: operationId: tenants_createOrReplaceDefaultPreferencesForTopic tags: - Tenants parameters: - name: tenant_id in: path description: Id of the tenant to update the default preferences for. required: true schema: type: string examples: Example1: value: tenantABC - name: topic_id in: path description: Id of the subscription topic you want to have a default preference for. required: true schema: type: string examples: Example1: value: pt_01kx4h2jdafq8bk99ws4ktbesd responses: '204': description: '' summary: Create or Replace Default Preferences For Topic security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionTopicNew' examples: Example1: value: status: OPTED_IN has_custom_routing: true custom_routing: - inbox delete: operationId: tenants_removeDefaultPreferencesForTopic tags: - Tenants parameters: - name: tenant_id in: path description: Id of the tenant to update the default preferences for. required: true schema: type: string - name: topic_id in: path description: Id of the subscription topic you want to have a default preference for. required: true schema: type: string responses: '204': description: '' summary: Remove Default Preferences For Topic security: - BearerAuth: [] /users/{user_id}/tenants: get: description: Returns a paginated list of user tenant associations. operationId: users_tenants_list tags: - User Tenants parameters: - name: user_id in: path description: Id of the user to retrieve all associated tenants for. required: true schema: type: string - name: limit in: query description: |- The number of accounts to return (defaults to 20, maximum value of 100) required: false schema: type: integer nullable: true - name: cursor in: query description: Continue the pagination with the next cursor required: false schema: type: string nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UsersListTenantsForUserResponse' examples: Example: value: items: - user_id: user_123 type: user tenant_id: tenant_abc profile: {} has_more: true url: https://example.com next_url: https://example.com cursor: MTpFWUNFRkRRN0c1WERTRTU2 type: list summary: Get tenants associated with a given user security: - BearerAuth: [] put: description: |- This endpoint is used to add a user to multiple tenants in one call. A custom profile can also be supplied for each tenant. This profile will be merged with the user's main profile when sending to the user with that tenant. operationId: users_tenants_addMultiple tags: - User Tenants parameters: - name: user_id in: path description: The user's ID. This can be any uniquely identifiable string. required: true schema: type: string responses: '204': description: '' summary: Add a User to Multiple Tenants security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: tenants: type: array items: $ref: '#/components/schemas/UserTenantAssociation' required: - tenants delete: description: Removes a user from any tenants they may have been associated with. operationId: users_tenants_removeAll tags: - User Tenants parameters: - name: user_id in: path description: Id of the user to be removed from the supplied tenant. required: true schema: type: string responses: '204': description: '' summary: Remove User From All Associated Tenants security: - BearerAuth: [] /users/{user_id}/tenants/{tenant_id}: put: description: |- This endpoint is used to add a single tenant. A custom profile can also be supplied with the tenant. This profile will be merged with the user's main profile when sending to the user with that tenant. operationId: users_tenants_add tags: - User Tenants parameters: - name: user_id in: path description: Id of the user to be added to the supplied tenant. required: true schema: type: string - name: tenant_id in: path description: Id of the tenant the user should be added to. required: true schema: type: string responses: '204': description: '' summary: Add a User to a Single Tenant security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: profile: type: object additionalProperties: true nullable: true delete: description: Removes a user from the supplied tenant. operationId: users_tenants_remove tags: - User Tenants parameters: - name: user_id in: path description: Id of the user to be removed from the supplied tenant. required: true schema: type: string - name: tenant_id in: path description: Id of the tenant the user should be removed from. required: true schema: type: string responses: '204': description: '' summary: Remove User from a Tenant security: - BearerAuth: [] /users/{user_id}/preferences: get: description: Fetch all user preferences. operationId: users_preferences_list tags: - User Preferences parameters: - name: user_id in: path description: A unique identifier associated with the user whose preferences you wish to retrieve. required: true schema: type: string - name: tenant_id in: query description: Query the preferences of a user for this specific tenant context. required: false schema: type: string nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UsersUserPreferencesListResponse' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true items: - custom_routing: - direct_message default_status: OPTED_IN has_custom_routing: true status: OPTED_IN topic_id: pt_01kx4h2jdafq8bk99mj9q2gsa2 topic_name: string '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Get user's preferences security: - BearerAuth: [] post: description: >- Additively create or update a user's preferences for one or more subscription topics in a single request. Only the topics included in the request body are created or updated; any existing overrides for topics not listed are left untouched. Structural validation of the request body fails fast with a single `400`. Beyond that, each topic is processed independently (partial-success, not all-or-nothing): valid topics are written and returned in `items`, while topics that cannot be applied are collected in `errors` with a per-topic `reason` (for example an unknown topic, a `REQUIRED` topic that cannot be opted out, a custom routing request that is not available on the workspace's plan, or a write failure). The request therefore returns `200` with both lists whenever the body is structurally valid. Every `topic_id` in the response — in both `items` and `errors` — is returned in Courier's canonical topic id form, regardless of the form supplied in the request. operationId: users_preferences_bulk_update tags: - User Preferences parameters: - name: user_id in: path description: A unique identifier associated with the user whose preferences you wish to update. required: true schema: type: string examples: Example1: value: abc-123 - name: tenant_id in: query description: Update the preferences of a user for this specific tenant context. required: false schema: type: string nullable: true responses: '200': description: >- The bulk update was applied. `items` contains the resulting topic overrides that were created or updated, and `errors` lists any topics that could not be applied, each with a reason. content: application/json: schema: $ref: '#/components/schemas/UsersBulkUpdatePreferencesResponse' examples: Example1: value: items: - topic_id: pt_01kx4h2jdafq8bk996nn92357r status: OPTED_IN has_custom_routing: true custom_routing: - inbox - email errors: - topic_id: pt_01kx4h2jdafq8bk99eyt3dx43x reason: Topic pt_01kx4h2jdafq8bk99eyt3dx43x not found '400': description: >- The request was malformed and nothing was applied — for example a missing or oversized `topics` array, unknown properties, or malformed JSON. content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '429': description: Too many requests; the client has been rate limited. content: application/json: schema: $ref: '#/components/schemas/TooManyRequests' examples: Example: value: message: Too Many Requests type: rate_limit_error summary: Update user preferences in bulk security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UsersBulkUpdatePreferencesParams' examples: Example1: value: topics: - topic_id: pt_01kx4h2jdafq8bk996nn92357r status: OPTED_IN has_custom_routing: true custom_routing: - inbox - email - topic_id: pt_01kx4h2jdafq8bk99eyt3dx43x status: OPTED_OUT put: description: >- Replace a user's complete set of preference overrides in a single request. The topics in the request body become the recipient's entire set of overrides: listed topics are created or updated, and every existing override that is not included in the body is reset to its topic default. Submitting an empty `topics` array is a valid clear-all that resets every existing override. This operation is validation-atomic (all-or-nothing): structural validation fails fast with a single `400`, and if any topic is semantically invalid (an unknown topic, a `REQUIRED` topic that cannot be opted out, or a custom routing request that is not available on the workspace's plan) the request returns a single `400` aggregating every failure in `errors` and writes nothing. On success it returns `200` with `items` (the complete resulting override set) and `deleted` (the ids of the overrides that were reset to default). Every `topic_id` in the response — in `items`, `deleted`, and any `errors` — is returned in Courier's canonical topic id form, regardless of the form supplied in the request. operationId: users_preferences_bulk_replace tags: - User Preferences parameters: - name: user_id in: path description: A unique identifier associated with the user whose preferences you wish to update. required: true schema: type: string examples: Example1: value: abc-123 - name: tenant_id in: query description: Replace the preferences of a user for this specific tenant context. required: false schema: type: string nullable: true responses: '200': description: >- The replacement was applied. `items` contains the complete resulting set of topic overrides for the user, and `deleted` lists the ids of the overrides that were reset to their topic default. content: application/json: schema: $ref: '#/components/schemas/UsersBulkReplacePreferencesResponse' examples: Example1: value: items: - topic_id: pt_01kx4h2jdafq8bk996nn92357r status: OPTED_IN has_custom_routing: true custom_routing: - inbox - email deleted: - pt_01kx4h2jdafq8bk99eyt3dx43x '400': description: >- The request was rejected and nothing was applied. Semantic validation failures (unknown topic, a REQUIRED topic that cannot be opted out, or plan-gated custom routing) are aggregated into UsersBulkPreferenceValidationError (with a per-topic errors list). Structural failures (missing/oversized topics, unknown properties, malformed JSON) return the standard BadRequest shape. content: application/json: schema: oneOf: - $ref: '#/components/schemas/UsersBulkPreferenceValidationError' - $ref: '#/components/schemas/BadRequest' examples: Semantic: value: message: One or more preferences could not be updated errors: - topic_id: pt_01kx4h2jdafq8bk99eyt3dx43x reason: Topic pt_01kx4h2jdafq8bk99eyt3dx43x not found Structural: value: message: 'topics: Too big: expected array to have <=50 items' type: invalid_request_error '429': description: Too many requests; the client has been rate limited. content: application/json: schema: $ref: '#/components/schemas/TooManyRequests' examples: Example: value: message: Too Many Requests type: rate_limit_error summary: Replace user preferences in bulk security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UsersBulkReplacePreferencesParams' examples: Example1: value: topics: - topic_id: pt_01kx4h2jdafq8bk996nn92357r status: OPTED_IN has_custom_routing: true custom_routing: - inbox - email /users/{user_id}/preferences/{topic_id}: get: description: Fetch user preferences for a specific subscription topic. operationId: users_preferences_get tags: - User Preferences parameters: - name: user_id in: path description: A unique identifier associated with the user whose preferences you wish to retrieve. required: true schema: type: string - name: topic_id in: path description: A unique identifier associated with a subscription topic. required: true schema: type: string - name: tenant_id in: query description: Query the preferences of a user for this specific tenant context. required: false schema: type: string nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UsersUserPreferencesGetResponse' examples: Example: value: topic: custom_routing: - direct_message default_status: OPTED_IN has_custom_routing: true status: OPTED_IN topic_id: pt_01kx4h2jdafq8bk99mj9q2gsa2 topic_name: string '404': description: '' content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Get user subscription topic security: - BearerAuth: [] put: description: Update or Create user preferences for a specific subscription topic. operationId: users_preferences_update tags: - User Preferences parameters: - name: user_id in: path description: A unique identifier associated with the user whose preferences you wish to retrieve. required: true schema: type: string examples: Example1: value: abc-123 - name: topic_id in: path description: A unique identifier associated with a subscription topic. required: true schema: type: string examples: Example1: value: pt_01kx4h2jdafq8bk996nn92357r - name: tenant_id in: query description: Update the preferences of a user for this specific tenant context. required: false schema: type: string nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UsersUserPreferencesUpdateResponse' examples: Example1: value: message: success '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Update or Create user preferences for a specific subscription topic security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: topic: $ref: '#/components/schemas/UsersTopicPreferenceUpdate' required: - topic examples: Example1: value: topic: status: OPTED_IN has_custom_routing: true custom_routing: - inbox - email delete: description: >- Remove a user's preferences for a specific subscription topic, resetting the topic to its effective default. This operation is idempotent: deleting a preference that does not exist succeeds with no error. operationId: users_preferences_delete tags: - User Preferences parameters: - name: user_id in: path description: A unique identifier associated with the user whose preferences you wish to delete. required: true schema: type: string examples: Example1: value: abc-123 - name: topic_id in: path description: A unique identifier associated with a subscription topic. required: true schema: type: string examples: Example1: value: pt_01kx4h2jdafq8bk996nn92357r - name: tenant_id in: query description: Delete the preferences of a user for this specific tenant context. required: false schema: type: string nullable: true responses: '204': description: The user's topic preference was deleted, or did not exist. summary: Delete user subscription topic security: - BearerAuth: [] /digests/schedules/{schedule_id}/trigger: post: description: >- Send a digest now instead of waiting for its scheduled time, so your users get what they have collected so far right away. operationId: digests_release tags: - Digests parameters: - name: schedule_id in: path description: >- The ID of the digest schedule to release, in the form `sch/{uuid}`. The value must be URL-encoded (e.g. `sch%2F00000000-0000-0000-0000-000000000000`). required: true schema: type: string responses: '204': description: >- The digest schedule was released. A `204` is also returned when the schedule currently has no in-progress digest instances to release. '403': description: The digest schedule does not belong to the authenticated workspace. content: application/json: schema: type: object properties: message: type: string examples: Unauthorized: value: message: Unauthorized summary: Release a digest early security: - BearerAuth: [] /digests/schedules/{schedule_id}/instances: get: description: >- List the digest instances for a schedule. Each instance represents the events accumulated for a single user against the schedule, and can be used to monitor digest accumulation before the digest is released. operationId: digests_listInstances tags: - Digests parameters: - name: schedule_id in: path description: >- The ID of the digest schedule, in the form `sch/{uuid}`. The value must be URL-encoded (e.g. `sch%2F00000000-0000-0000-0000-000000000000`). required: true schema: type: string - name: cursor in: query description: A cursor token from a previous response, used to fetch the next page of results. required: false schema: type: string - name: limit in: query description: The maximum number of digest instances to return. Defaults to 20, with a maximum of 100. required: false schema: type: integer default: 20 maximum: 100 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/DigestInstanceListResponse' examples: Example1: value: type: list has_more: false cursor: null url: /digests/schedules/sch%2F00000000-0000-0000-0000-000000000000/instances next_url: null items: - digest_instance_id: a1b2c3d4-0000-0000-0000-000000000000 status: IN_PROGRESS event_count: 3 user_id: user-123 tenant_id: tenant-abc disabled: false created_at: '2024-01-01T00:00:00.000Z' categories: - category_key: comments retain: first category_key_counts: comments: 3 '403': description: The digest schedule does not belong to the authenticated workspace. content: application/json: schema: type: object properties: message: type: string examples: Unauthorized: value: message: Unauthorized summary: List digest instances security: - BearerAuth: [] /users/{user_id}/tokens: get: description: Gets all tokens available for a :user_id operationId: users_tokens_list tags: - Device Tokens parameters: - name: user_id in: path description: The user's ID. This can be any uniquely identifiable string. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UsersGetAllTokensResponse' examples: Example: value: tokens: - token: string provider_key: firebase-fcm expiry_date: string properties: {} device: app_id: abc-123 ad_id: abc-123 device_id: abc-123 platform: string manufacturer: string model: string tracking: os_version: string ip: string lat: string long: string '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Get all tokens security: - BearerAuth: [] put: description: Adds multiple tokens to a user and overwrites matching existing tokens. operationId: users_tokens_addMultiple tags: - Device Tokens parameters: - name: user_id in: path description: The user's ID. This can be any uniquely identifiable string. required: true schema: type: string responses: '204': description: '' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Add multiple tokens to user security: - BearerAuth: [] /users/{user_id}/tokens/{token}: get: description: Get single token available for a `:token` operationId: users_tokens_get tags: - Device Tokens parameters: - name: user_id in: path description: The user's ID. This can be any uniquely identifiable string. required: true schema: type: string - name: token in: path description: The full token string. required: true schema: type: string x-stainless-param: token_id responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UsersGetUserTokenResponse' examples: Example: value: token: string provider_key: firebase-fcm expiry_date: string properties: {} device: app_id: abc-123 ad_id: abc-123 device_id: abc-123 platform: string manufacturer: string model: string tracking: os_version: string ip: string lat: string long: string status: active status_reason: active '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Get single token security: - BearerAuth: [] put: description: Adds a single token to a user and overwrites a matching existing token. operationId: users_tokens_add tags: - Device Tokens parameters: - name: user_id in: path description: The user's ID. This can be any uniquely identifiable string. required: true schema: type: string - name: token in: path description: The full token string. required: true schema: type: string x-stainless-param: token_id responses: '204': description: '' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Add single token to user security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UsersAddSingleTokenBody' patch: description: Apply a JSON Patch (RFC 6902) to the specified token. operationId: users_tokens_update tags: - Device Tokens parameters: - name: user_id in: path description: The user's ID. This can be any uniquely identifiable string. required: true schema: type: string - name: token in: path description: The full token string. required: true schema: type: string x-stainless-param: token_id responses: '204': description: '' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Update a token security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UsersPatchUserTokenOpts' delete: operationId: users_tokens_delete tags: - Device Tokens parameters: - name: user_id in: path description: The user's ID. This can be any uniquely identifiable string. required: true schema: type: string - name: token in: path description: The full token string. required: true schema: type: string x-stainless-param: token_id responses: '204': description: '' summary: Delete User Token security: - BearerAuth: [] /automations: get: description: Get the list of automations. operationId: automations_list tags: - Automations parameters: - name: cursor in: query description: >- A cursor token for pagination. Use the cursor from the previous response to fetch the next page of results. required: false schema: type: string - name: version in: query description: >- The version of templates to retrieve. Accepted values are published (for published templates) or draft (for draft templates). Defaults to published. required: false schema: type: string enum: - published - draft default: published responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/AutomationTemplateListResponse' examples: Example1: value: templates: - name: Welcome Email Automation id: abc-123-def-456 version: published createdAt: '2024-01-01T00:00:00Z' updatedAt: '2024-01-02T00:00:00Z' - name: Order Confirmation id: xyz-789-ghi-012 version: published createdAt: '2024-01-03T00:00:00Z' updatedAt: '2024-01-04T00:00:00Z' cursor: eyJpZCI6InRlbXBsYXRlLTIifQ== '400': description: Bad Request content: application/json: schema: type: object properties: message: type: string examples: InvalidVersion: value: message: >- Invalid version parameter "invalid". Accepted values are: published (for published templates) or draft (for draft templates) InvalidCursor: value: message: Invalid cursor format summary: List Automations security: - BearerAuth: [] /automations/{templateId}/invoke: post: description: Invoke an automation run from an automation template. operationId: automations_invokeAutomationTemplate tags: - Automations parameters: - name: templateId in: path description: >- A unique identifier representing the automation template to be invoked. This could be the Automation Template ID or the Automation Template Alias. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/AutomationInvokeResponse' examples: Example: value: runId: abc-123 summary: Invoke an Automation security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AutomationInvokeParams' /automations/invoke: post: description: >- Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a series of automation steps. For information about what steps are available, checkout the ad hoc automation guide [here](https://www.courier.com/docs/automations/steps/). operationId: automations_invokeAdHocAutomation tags: - Automations parameters: [] responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/AutomationInvokeResponse' examples: Example1: value: runId: 1-65f240a0-47a6a120c8374de9bcf9f22c summary: Invoke an Ad Hoc Automation security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AutomationAdHocInvokeParams' examples: Example1: value: data: name: Foo profile: tenant_id: abc-123 recipient: user-yes automation: cancelation_token: delay-send--user-yes--abc-123 steps: - action: delay until: 20240408T080910.123 - action: send template: 64TP5HKPFTM8VTK1Y75SJDQX9JK0 /journeys: get: description: Get the list of journeys. operationId: journeys_list tags: - Journeys parameters: - name: cursor in: query description: >- A cursor token for pagination. Use the cursor from the previous response to fetch the next page of results. required: false schema: type: string - name: version in: query description: >- The version of journeys to retrieve. Accepted values are published (for published journeys) or draft (for draft journeys). Defaults to published. required: false schema: type: string enum: - published - draft default: published responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/JourneysListResponse' examples: Example1: value: templates: - name: Welcome Journey id: jry_01kx4m9ntsfk6vny01z4ttha0p version: published createdAt: '2024-01-01T00:00:00Z' updatedAt: '2024-01-02T00:00:00Z' - name: Onboarding Flow id: jry_01kx4m9ntsfk6vny08tx3qssyn version: published createdAt: '2024-01-03T00:00:00Z' updatedAt: '2024-01-04T00:00:00Z' cursor: eyJpZCI6InRlbXBsYXRlLTIifQ== '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: InvalidVersion: value: type: invalid_request_error message: >- Invalid version parameter "invalid". Accepted values are: published (for published templates) or draft (for draft templates) InvalidCursor: value: type: invalid_request_error message: Invalid cursor format summary: List Journeys security: - BearerAuth: [] post: operationId: journeys_create summary: Create a journey description: >- Create a journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to publish on create. Send nodes are not allowed on `POST`. The standard flow is: create the journey shell here, add notification templates with `POST /journeys/{templateId}/templates`, then wire them into the journey with `PUT /journeys/{templateId}`. Call `POST /journeys/{templateId}/publish` to publish a draft after the fact. tags: - Journeys requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateJourneyRequest' examples: Example1: summary: Welcome journey with a trigger and a send value: name: Welcome Journey state: DRAFT enabled: true nodes: - id: trigger-1 type: trigger trigger_type: api - id: send-1 type: send responses: '201': description: Journey created content: application/json: schema: $ref: '#/components/schemas/JourneyResponse' examples: Example1: summary: Created journey value: id: jry_01kx4m9ntrfk6vnxzww2rbpfd1 name: Welcome Journey state: DRAFT enabled: true nodes: [] created: 1715000000000 creator: user-1 updated: 1715000000000 updater: user-1 published: null '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] /journeys/cancel: post: operationId: journeys_cancel summary: Cancel journey runs description: >- Cancel journey runs. The request body must include EXACTLY ONE of `cancelation_token` (cancels every run associated with the token) or `run_id` (cancels a single tenant-scoped run). Supplying both or neither returns a `400`. A `run_id` that does not match a run for the tenant returns `404`. Cancelation is idempotent: a run that has already finished (`PROCESSED`/`ERROR`) or was already `CANCELED` is left unchanged and its current status is returned. tags: - Journeys requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CancelJourneyRequest' examples: ByCancelationToken: summary: Cancel every run for a cancelation token value: cancelation_token: order-1234 ByRunId: summary: Cancel a single run by id value: run_id: 1-5f0c3b9a-abcdef0123456789 responses: '202': description: Cancelation accepted content: application/json: schema: $ref: '#/components/schemas/CancelJourneyResponse' examples: ByCancelationToken: summary: Token branch value: cancelation_token: order-1234 ByRunId: summary: Run id branch value: run_id: 1-5f0c3b9a-abcdef0123456789 status: CANCELED '400': description: Bad request — both or neither of cancelation_token / run_id supplied content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: exactly one of cancelation_token or run_id is required type: invalid_request_error '404': description: A run_id was supplied but no matching run exists for this tenant content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: run not found type: invalid_request_error '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] /journeys/{templateId}/invoke: post: description: >- Invoke a journey by id or alias to start a new run. The response includes a `runId` identifying the run. operationId: journeys_invoke tags: - Journeys parameters: - name: templateId in: path description: A unique identifier representing the journey to be invoked. Accepts a Journey ID or Journey Alias. required: true schema: type: string responses: '202': description: Journey invocation accepted content: application/json: schema: $ref: '#/components/schemas/JourneysInvokeResponse' examples: Example1: value: runId: 1-65f240a0-47a6a120c8374de9bcf9f22c '400': description: Bad Request - validation error, invalid version, or missing recipient content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: MissingTemplateId: value: type: invalid_request_error message: templateId is required MissingRecipient: value: type: invalid_request_error message: >- User identifier or profile required. Provide user_id, user_id/userId/anonymousId in profile/data, or profile with contact info. InvalidVersion: value: type: invalid_request_error message: Invalid automation version. Expected 2025-09-03, got 2022-12-01 '404': description: Journey not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: TemplateNotFound: value: type: invalid_request_error message: Automation template abc-123 not found '422': description: Unprocessable Entity - trigger conditions failed, template archived or disabled content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: TriggerConditionFailed: value: type: invalid_request_error message: Trigger conditions not met ArchivedTemplate: value: type: invalid_request_error message: Cannot invoke archived automation template abc-123 DisabledTemplate: value: type: invalid_request_error message: Cannot invoke disabled automation template abc-123 summary: Invoke a journey security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/JourneysInvokeRequest' examples: WithUserId: summary: Invoke with user_id value: user_id: user-123 data: order_id: order-456 amount: 99.99 WithProfile: summary: Invoke with profile containing contact info value: profile: email: user@example.com first_name: John data: welcome_message: Hello! WithUserIdInProfile: summary: Invoke with user_id in profile value: profile: user_id: user-123 email: user@example.com data: foo: bar WithTenantScopedProfile: summary: Invoke with tenant-scoped profile description: Load a user's profile scoped to a specific tenant value: user_id: doctor-smith profile: context: tenant_id: hospital-a data: report_date: '2024-01-15' /journeys/{templateId}: get: operationId: journeys_get summary: Fetch a journey by id description: >- Fetch a journey by id. Pass `?version=draft` (default `published`) to retrieve the working draft, or `?version=vN` to retrieve a historical version. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id - in: query name: version description: 'Version selector: `draft`, `published` (default), or `vN`.' schema: type: string pattern: ^(?:v\d+|draft|published)$ responses: '200': description: Journey content: application/json: schema: $ref: '#/components/schemas/JourneyResponse' examples: Example1: summary: Published journey value: id: jry_01kx4m9ntrfk6vnxzww2rbpfd1 name: Welcome Journey state: PUBLISHED enabled: true nodes: [] created: 1715000000000 creator: user-1 updated: 1715000100000 updater: user-1 published: 1715000200000 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] put: operationId: journeys_replace summary: Replace a journey description: >- Replace the journey draft. Updates the working draft only; call `POST /journeys/{templateId}/publish` to make it live, or pass `state: "PUBLISHED"` in this request to publish immediately. Send-node `template` ids must already exist and be scoped to this journey, and node ids must not be claimed by another journey. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateJourneyRequest' examples: Example1: summary: Replace draft value: name: Welcome Journey v2 state: DRAFT enabled: true nodes: [] responses: '200': description: Updated journey content: application/json: schema: $ref: '#/components/schemas/JourneyResponse' examples: Example1: summary: Updated journey value: id: jry_01kx4m9ntrfk6vnxzww2rbpfd1 name: Welcome Journey v2 state: DRAFT enabled: true nodes: [] created: 1715000000000 creator: user-1 updated: 1715000300000 updater: user-1 published: 1715000200000 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] delete: operationId: journeys_archive summary: Archive a journey description: Archive a journey. Archived journeys cannot be invoked. Existing journey runs continue to completion. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id responses: '204': description: Archived '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] /journeys/{templateId}/versions: get: operationId: journeys_listVersions summary: List versions of a journey description: List published versions of a journey, ordered most recent first. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id responses: '200': description: Version list content: application/json: schema: $ref: '#/components/schemas/JourneyVersionsListResponse' examples: Example1: summary: Two versions value: results: - version: v2 name: Welcome Journey created: 1715000400000 creator: user-1 published: 1715000400000 - version: v1 name: Welcome Journey created: 1715000200000 creator: user-1 published: 1715000200000 paging: more: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] /journeys/{templateId}/publish: post: operationId: journeys_publish summary: Publish a journey description: >- Publish the current draft as a new version. Body is optional; pass `{ "version": "vN" }` to roll back to a prior version instead. Returns 404 if the journey has no draft to publish. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id requestBody: content: application/json: schema: $ref: '#/components/schemas/JourneyPublishRequest' examples: Example1: summary: Publish draft value: {} responses: '200': description: Published journey content: application/json: schema: $ref: '#/components/schemas/JourneyResponse' examples: Example1: summary: Published journey value: id: jry_01kx4m9ntrfk6vnxzww2rbpfd1 name: Welcome Journey state: PUBLISHED enabled: true nodes: [] created: 1715000000000 creator: user-1 updated: 1715000300000 updater: user-1 published: 1715000400000 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] /journeys/{templateId}/templates: get: operationId: journeys_listTemplates summary: List notification templates scoped to a journey description: >- List notification templates scoped to this journey. Journey-scoped notification templates can only be referenced from `send` nodes within the same journey. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id - in: query name: cursor description: Pagination cursor from a prior response. schema: type: string - in: query name: limit description: Page size. Minimum 1, maximum 100. schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Notification template list content: application/json: schema: $ref: '#/components/schemas/JourneyTemplateListResponse' examples: Example1: summary: Two notification templates value: results: - id: nt_01kx4m9ntsfk6vny0k8crygtc5 name: Welcome email tags: [] state: PUBLISHED created: 1715000000000 creator: user-1 - id: nt_01kx4m9ntsfk6vny0zvwbzpnpb name: Welcome push tags: [] state: PUBLISHED created: 1715000100000 creator: user-1 paging: more: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] post: operationId: journeys_createTemplate summary: Create a notification template scoped to a journey description: >- Create a notification template scoped to this journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to publish on create. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/JourneyTemplateCreateRequest' examples: Example1: summary: Email notification template value: channel: email notification: name: Welcome email tags: [] brand: null subscription: null content: version: '2022-01-01' elements: - type: text content: Welcome! responses: '201': description: Created notification template content: application/json: schema: $ref: '#/components/schemas/JourneyTemplateGetResponse' examples: Example1: summary: Created notification template value: name: Welcome email tags: [] brand: null subscription: null content: scope: default version: '2022-01-01' elements: [] '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] /journeys/{templateId}/templates/{notificationId}: get: operationId: journeys_getTemplate summary: Fetch a journey-scoped notification template by id description: >- Fetch a journey-scoped notification template by id. Pass `?version=draft` (default `published`) to retrieve the working draft, or `?version=vN` for a historical version. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id - in: path name: notificationId schema: type: string minLength: 1 required: true description: Notification template id responses: '200': description: Notification template content: application/json: schema: $ref: '#/components/schemas/JourneyTemplateGetResponse' examples: Example1: summary: Published notification template value: name: Welcome email tags: [] brand: null subscription: null content: scope: default version: '2022-01-01' elements: [] '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] put: operationId: journeys_replaceTemplate summary: Replace a journey-scoped notification template description: Replace the journey-scoped notification template draft. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id - in: path name: notificationId schema: type: string minLength: 1 required: true description: Notification template id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/JourneyTemplateReplaceRequest' examples: Example1: summary: Replace draft value: name: Welcome email v2 tags: [] brand: null subscription: null content: version: '2022-01-01' elements: [] responses: '200': description: Updated notification template content: application/json: schema: $ref: '#/components/schemas/JourneyTemplateGetResponse' examples: Example1: summary: Updated notification template value: name: Welcome email v2 tags: [] brand: null subscription: null content: scope: default version: '2022-01-01' elements: [] '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] delete: operationId: journeys_archiveTemplate summary: Archive a journey-scoped notification template description: Archive the journey-scoped notification template. Archived templates cannot be sent. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id - in: path name: notificationId schema: type: string minLength: 1 required: true description: Notification template id responses: '204': description: Archived '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] /journeys/{templateId}/templates/{notificationId}/publish: post: operationId: journeys_publishTemplate summary: Publish a journey-scoped notification template description: >- Publish the current draft of the journey-scoped notification template as a new version. Optionally roll back to a prior version by passing `{ "version": "vN" }`. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id - in: path name: notificationId schema: type: string minLength: 1 required: true description: Notification template id requestBody: content: application/json: schema: $ref: '#/components/schemas/JourneyTemplatePublishRequest' examples: Example1: summary: Publish value: {} responses: '204': description: Published notification template '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] /journeys/{templateId}/templates/{notificationId}/versions: get: operationId: journeys_listTemplateVersions summary: List versions of a journey-scoped notification template description: List published versions of the journey-scoped notification template, ordered most recent first. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id - in: path name: notificationId schema: type: string minLength: 1 required: true description: Notification template id responses: '200': description: Notification template version list content: application/json: schema: $ref: '#/components/schemas/NotificationTemplateVersionListResponse' examples: Example1: summary: Two versions value: versions: - version: v2 created: 1715000400000 creator: user-1 - version: v1 created: 1715000200000 creator: user-1 paging: more: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] /journeys/{templateId}/templates/{notificationId}/content: get: operationId: journeys_getTemplateContent summary: Fetch the content of a journey-scoped notification template description: >- Retrieve the elemental content of a journey-scoped notification template. The response contains the versioned elements along with their content checksums, which can be used to detect changes between versions. Pass `?version=draft` (default `published`) to retrieve the working draft, or `?version=vN` for a historical version. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id - in: path name: notificationId schema: type: string minLength: 1 required: true description: Notification template id - in: query name: version required: false schema: type: string description: Accepts `draft`, `published`, or a version string (e.g., `v001`). Defaults to `published`. examples: published: value: published summary: Current published version (default) draft: value: draft summary: Current draft version historical: value: v001 summary: Specific historical version responses: '200': description: Scoped notification content content: application/json: schema: $ref: '#/components/schemas/NotificationContentGetResponse' examples: Example1: summary: Elemental content response value: version: '2022-01-01' elements: - id: elem_channel_1 type: channel checksum: abc123def456 elements: - id: elem_meta_1 type: meta checksum: meta_abc123 - id: elem_text_1 type: text checksum: text_abc123 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] put: operationId: journeys_replaceTemplateContent summary: Replace the content of a journey-scoped notification template description: >- Replace the elemental content of a journey-scoped notification template. Overwrites all elements in the template draft with the provided content. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id - in: path name: notificationId schema: type: string minLength: 1 required: true description: Notification template id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotificationContentPutRequest' examples: Example1: summary: Replace all content elements value: content: version: '2022-01-01' elements: - type: channel channel: email elements: - type: meta title: Welcome! - type: text content: Hello {{data.name}}. state: DRAFT responses: '200': description: Updated scoped notification content content: application/json: schema: $ref: '#/components/schemas/NotificationContentMutationResponse' examples: Example1: summary: Content replaced successfully value: id: nt_01kx4h2jdafq8bk9aftxak4b40 version: '2022-01-01' elements: - id: elem_1 checksum: abc123 - id: elem_2 checksum: def456 state: DRAFT '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] /journeys/{templateId}/templates/{notificationId}/locales/{localeId}: put: operationId: journeys_replaceTemplateLocale summary: Replace a single locale of a journey-scoped notification template description: >- Set locale-specific content overrides for a journey-scoped notification template. Each element override must reference an existing element by ID. tags: - Journeys parameters: - in: path name: templateId schema: type: string minLength: 1 required: true description: Journey id - in: path name: notificationId schema: type: string minLength: 1 required: true description: Notification template id - in: path name: localeId schema: type: string minLength: 1 required: true description: Locale code (e.g., `es`, `fr`, `pt-BR`). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotificationLocalePutRequest' examples: Example1: summary: Set Spanish locale overrides value: elements: - id: elem_1 content: Hola {{data.name}}. - id: elem_2 title: Bienvenido! state: DRAFT responses: '200': description: Updated scoped notification locale content: application/json: schema: $ref: '#/components/schemas/NotificationContentMutationResponse' examples: Example1: summary: Locale content set successfully value: id: nt_01kx4h2jdafq8bk9aftxak4b40 version: '2022-01-01' elements: - id: elem_1 checksum: abc123 - id: elem_2 checksum: def456 state: DRAFT '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' examples: Example: value: message: Example message text type: invalid_request_error security: - BearerAuth: [] /brands: post: operationId: brands_create tags: - Brands parameters: [] responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Brand' examples: Example: value: id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag name: Default Brand published: 1 created: 1 updated: 1 settings: colors: primary: string secondary: string email: templateOverride: backgroundColor: string blocksBackgroundColor: string enabled: true footer: string head: string header: string width: string mjml: backgroundColor: string blocksBackgroundColor: string enabled: true footer: string head: string header: string width: string footerBackgroundColor: string footerFullWidth: true head: inheritDefault: true content: string footer: content: string inheritDefault: true header: inheritDefault: true barColor: string logo: href: https://example.com image: string inapp: borderRadius: string disableMessageIcon: true fontFamily: string placement: top widgetBackground: topColor: string bottomColor: string colors: primary: string secondary: string icons: bell: string message: Example message text snippets: items: - name: Default Brand value: string version: string '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '402': description: '' content: application/json: schema: $ref: '#/components/schemas/PaymentRequired' examples: Example: value: message: Example message text type: authorization_error '409': description: '' content: application/json: schema: $ref: '#/components/schemas/AlreadyExists' examples: Example: value: message: Example message text type: invalid_request_error summary: Create a new brand description: >- Create a new brand. Requires `name` and `settings` (with at least `colors.primary` and `colors.secondary`). security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrandParameters' examples: MinimalBrand: summary: Minimal brand with required fields value: name: My Brand settings: colors: primary: '#9D3789' secondary: '#FFFFFF' get: description: Get the list of brands. operationId: brands_list tags: - Brands parameters: - name: cursor in: query description: A unique identifier that allows for fetching the next set of brands. required: false schema: type: string nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/BrandsResponse' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true results: - id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag name: Default Brand published: 1 created: 1 updated: 1 settings: colors: primary: string secondary: string email: templateOverride: backgroundColor: string blocksBackgroundColor: string enabled: true footer: string head: string header: string width: string mjml: backgroundColor: string blocksBackgroundColor: string enabled: true footer: string head: string header: string width: string footerBackgroundColor: string footerFullWidth: true head: inheritDefault: true content: string footer: content: string inheritDefault: true header: inheritDefault: true barColor: string logo: href: https://example.com image: string inapp: borderRadius: string disableMessageIcon: true fontFamily: string placement: top widgetBackground: topColor: string bottomColor: string colors: primary: string secondary: string icons: bell: string message: Example message text snippets: items: - name: Default Brand value: string version: string summary: List brands security: - BearerAuth: [] /brands/{brand_id}: get: description: Fetch a specific brand by brand ID. operationId: brands_get tags: - Brands parameters: - name: brand_id in: path description: A unique identifier associated with the brand you wish to retrieve. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Brand' examples: Example: value: id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag name: Default Brand published: 1 created: 1 updated: 1 settings: colors: primary: string secondary: string email: templateOverride: backgroundColor: string blocksBackgroundColor: string enabled: true footer: string head: string header: string width: string mjml: backgroundColor: string blocksBackgroundColor: string enabled: true footer: string head: string header: string width: string footerBackgroundColor: string footerFullWidth: true head: inheritDefault: true content: string footer: content: string inheritDefault: true header: inheritDefault: true barColor: string logo: href: https://example.com image: string inapp: borderRadius: string disableMessageIcon: true fontFamily: string placement: top widgetBackground: topColor: string bottomColor: string colors: primary: string secondary: string icons: bell: string message: Example message text snippets: items: - name: Default Brand value: string version: string summary: Get a brand security: - BearerAuth: [] put: description: Replace an existing brand with the supplied values. operationId: brands_replace tags: - Brands parameters: - name: brand_id in: path description: A unique identifier associated with the brand you wish to update. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Brand' examples: Example: value: id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag name: Default Brand published: 1 created: 1 updated: 1 settings: colors: primary: string secondary: string email: templateOverride: backgroundColor: string blocksBackgroundColor: string enabled: true footer: string head: string header: string width: string mjml: backgroundColor: string blocksBackgroundColor: string enabled: true footer: string head: string header: string width: string footerBackgroundColor: string footerFullWidth: true head: inheritDefault: true content: string footer: content: string inheritDefault: true header: inheritDefault: true barColor: string logo: href: https://example.com image: string inapp: borderRadius: string disableMessageIcon: true fontFamily: string placement: top widgetBackground: topColor: string bottomColor: string colors: primary: string secondary: string icons: bell: string message: Example message text snippets: items: - name: Default Brand value: string version: string summary: Replace a brand security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: The name of the brand. settings: $ref: '#/components/schemas/BrandSettings' nullable: true snippets: $ref: '#/components/schemas/BrandSnippets' nullable: true required: - name delete: description: Delete a brand by brand ID. operationId: brands_delete tags: - Brands parameters: - name: brand_id in: path description: A unique identifier associated with the brand you wish to retrieve. required: true schema: type: string responses: '204': description: '' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/Conflict' examples: Example: value: message: Example message text type: invalid_request_error summary: Delete a brand security: - BearerAuth: [] /inbound/courier: post: operationId: inbound_track tags: - Inbound parameters: [] responses: '202': description: '' content: application/json: schema: $ref: '#/components/schemas/TrackAcceptedResponse' examples: Example1: value: messageId: 1-6952feeb-7fed6092da5363f2af38eb42 '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '409': description: '' content: application/json: schema: $ref: '#/components/schemas/Conflict' examples: Example: value: message: Example message text type: invalid_request_error summary: Courier Track Event security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InboundTrackEvent' examples: Example1: value: event: New Order Placed messageId: 4c62c457-b329-4bea-9bfc-17bba86c393f userId: '1234' type: track properties: order_id: 123 total_orders: 5 last_order_id: 122 /translations/{domain}/{locale}: get: description: Get translations by locale operationId: translations_get tags: - Translations parameters: - name: domain in: path description: The domain you want to retrieve translations for. Only `default` is supported at the moment required: true schema: type: string - name: locale in: path description: The locale you want to retrieve the translations for required: true schema: type: string responses: '200': description: .po file translation content content: application/json: schema: type: string examples: Example: value: string '404': description: '' content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Get a translation security: - BearerAuth: [] put: description: Update a translation operationId: translations_update tags: - Translations parameters: - name: domain in: path description: The domain you want to retrieve translations for. Only `default` is supported at the moment required: true schema: type: string - name: locale in: path description: The locale you want to retrieve the translations for required: true schema: type: string responses: '204': description: '' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Update translations by locale security: - BearerAuth: [] requestBody: description: .po file translation content required: true content: application/json: schema: type: string /tenants/{tenant_id}/templates/{template_id}: get: operationId: tenants_getTemplateByTenant tags: - Courier Create parameters: - name: tenant_id in: path description: Id of the tenant for which to retrieve the template. required: true schema: type: string - name: template_id in: path description: Id of the template to be retrieved. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GetTemplateByTenantResponse' examples: Example: value: id: tenant_abc created_at: '2024-01-15T10:30:00.000Z' updated_at: '2024-01-15T10:30:00.000Z' published_at: '2024-01-15T10:30:00.000Z' version: string data: routing: method: all channels: - string content: version: string elements: - type: text channels: - string ref: string if: string loop: string content: string align: left text_style: text color: string bold: string italic: string strikethrough: string underline: string locales: locales_key: content: string format: markdown '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Get a Template in Tenant security: - BearerAuth: [] put: operationId: tenants_replaceTemplate tags: - Courier Create description: | Creates or updates a notification template for a tenant. If the template already exists for the tenant, it will be updated (200). Otherwise, a new template is created (201). Optionally publishes the template immediately if the `published` flag is set to true. parameters: - name: tenant_id in: path description: Id of the tenant for which to create or update the template. required: true schema: type: string - name: template_id in: path description: Id of the template to be created or updated. required: true schema: type: string responses: '200': description: Template updated successfully content: application/json: schema: $ref: '#/components/schemas/PutTenantTemplateResponse' examples: Example: value: id: tenant_abc version: string published_at: '2024-01-15T10:30:00.000Z' '201': description: Template created successfully content: application/json: schema: $ref: '#/components/schemas/PutTenantTemplateResponse' examples: Example: value: id: tenant_abc version: string published_at: '2024-01-15T10:30:00.000Z' '400': description: Bad request - validation error content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Tenant not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error '413': description: Payload too large - template size exceeds maximum allowed content: application/json: schema: $ref: '#/components/schemas/PayloadTooLarge' examples: Example: value: message: Example message text type: invalid_request_error summary: Create or Update a Tenant Template security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PutTenantTemplateRequest' delete: operationId: tenants_deleteTemplate tags: - Courier Create description: | Deletes the tenant's notification template with the given `template_id`. Returns **204 No Content** with an empty body on success. Returns **404** if there is no template with this ID for the tenant, including a second `DELETE` after a successful removal. parameters: - name: tenant_id in: path description: Id of the tenant that owns the template. required: true schema: type: string - name: template_id in: path description: Id of the template to remove from the tenant. required: true schema: type: string responses: '204': description: Template deleted successfully '404': description: Tenant or template not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Delete a Tenant Template security: - BearerAuth: [] /tenants/{tenant_id}/templates/{template_id}/publish: post: operationId: tenants_publishTemplate tags: - Courier Create description: | Publishes a specific version of a notification template for a tenant. The template must already exist in the tenant's notification map. If no version is specified, defaults to publishing the "latest" version. parameters: - name: tenant_id in: path description: Id of the tenant that owns the template. required: true schema: type: string - name: template_id in: path description: Id of the template to be published. required: true schema: type: string responses: '200': description: Template published successfully content: application/json: schema: $ref: '#/components/schemas/PostTenantTemplatePublishResponse' examples: Example: value: id: tenant_abc version: string published_at: '2024-01-15T10:30:00.000Z' '400': description: Bad request - validation error content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Template or tenant not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Publish a Tenant Template security: - BearerAuth: [] requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/PostTenantTemplatePublishRequest' /tenants/{tenant_id}/templates/{template_id}/versions/{version}: get: operationId: tenants_getTemplateVersion tags: - Courier Create description: | Fetches a specific version of a tenant template. Supports the following version formats: - `latest` - The most recent version of the template - `published` - The currently published version - `v{version}` - A specific version (e.g., "v1", "v2", "v1.0.0") parameters: - name: tenant_id in: path description: Id of the tenant for which to retrieve the template. required: true schema: type: string - name: template_id in: path description: Id of the template to be retrieved. required: true schema: type: string - name: version in: path description: >- Version of the template to retrieve. Accepts "latest", "published", or a specific version string (e.g., "v1", "v2"). required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GetTemplateByTenantResponse' examples: Example: value: id: tenant_abc created_at: '2024-01-15T10:30:00.000Z' updated_at: '2024-01-15T10:30:00.000Z' published_at: '2024-01-15T10:30:00.000Z' version: string data: routing: method: all channels: - string content: version: string elements: - type: text channels: - string ref: string if: string loop: string content: string align: left text_style: text color: string bold: string italic: string strikethrough: string underline: string locales: locales_key: content: string format: markdown '400': description: Bad request - invalid version format content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Template, version, or tenant not found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Get a Specific Template Version security: - BearerAuth: [] /tenants/{tenant_id}/templates: get: operationId: tenants_getTemplateListByTenant tags: - Courier Create parameters: - name: tenant_id in: path description: Id of the tenant for which to retrieve the templates. required: true schema: type: string - name: limit in: query description: The number of templates to return (defaults to 20, maximum value of 100) required: false schema: type: integer nullable: true - name: cursor in: query description: Continue the pagination with the next cursor required: false schema: type: string nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ListTemplatesByTenantResponse' examples: Example: value: items: - id: example.list.id created_at: '2024-01-15T10:30:00.000Z' updated_at: '2024-01-15T10:30:00.000Z' published_at: '2024-01-15T10:30:00.000Z' version: string data: routing: method: all channels: - string has_more: true url: https://example.com next_url: https://example.com cursor: MTpFWUNFRkRRN0c1WERTRTU2 type: list '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: List Templates in Tenant security: - BearerAuth: [] /audit-events: get: description: Fetch the list of audit events operationId: auditEvents_list tags: - Audit Events parameters: - name: cursor in: query description: A unique identifier that allows for fetching the next set of audit events. required: false schema: type: string nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ListAuditEventsResponse' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true results: - auditEventId: abc-123 actor: id: abc-123 email: user@example.com target: string source: string timestamp: '2024-01-15T10:30:00.000Z' type: string summary: Get all audit events security: - BearerAuth: [] /audit-events/{audit-event-id}: get: description: Fetch a specific audit event by ID. operationId: auditEvents_get tags: - Audit Events parameters: - name: audit-event-id in: path description: A unique identifier associated with the audit event you wish to retrieve required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/AuditEvent' examples: Example: value: auditEventId: abc-123 actor: id: abc-123 email: user@example.com target: string source: string timestamp: '2024-01-15T10:30:00.000Z' type: string summary: Get an audit event security: - BearerAuth: [] /routing-strategies: get: description: >- List routing strategies in your workspace. Returns metadata only (no routing/channels/providers content). Use GET /routing-strategies/{id} for full details. operationId: routingStrategies_list tags: - Routing Strategies parameters: - name: cursor in: query description: Opaque pagination cursor from a previous response. Omit for the first page. required: false schema: type: string nullable: true - name: limit in: query description: Maximum number of results per page. Default 20, max 100. required: false schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RoutingStrategyListResponse' examples: WithResults: value: results: - id: rs_01kx4h2jdafq8bk9amzvy6hbv0 name: Email via SendGrid description: Routes email through sendgrid with SES failover tags: - production - email created: 1710000000000 creator: user_abc updated: 1710000000000 updater: user_def paging: cursor: eyJway... more: true Empty: value: results: [] paging: cursor: null more: false summary: List Routing Strategies security: - BearerAuth: [] post: description: >- Create a routing strategy. Requires a name and routing configuration at minimum. Channels and providers default to empty if omitted. operationId: routingStrategies_create tags: - Routing Strategies parameters: [] responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/RoutingStrategyGetResponse' examples: Example: value: id: rs_01kx4h2jdafq8bk9amzvy6hbv0 name: Example Name description: An example description. tags: - string routing: method: all channels: - string channels: channels_key: brand_id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag providers: - string routing_method: all if: string timeouts: provider: 1 channel: 1 override: {} metadata: utm: source: string medium: string campaign: string term: string content: string providers: providers_key: override: {} if: string timeouts: 1 metadata: utm: source: string medium: string campaign: string term: string content: string created: 1 creator: user_123 updated: 1 updater: user_123 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: ValidationError: value: type: invalid_request_error message: 'name: Required; routing: Required' summary: Create Routing Strategy security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RoutingStrategyCreateRequest' examples: FullExample: summary: Create a routing strategy with all fields value: name: Email via SendGrid description: Routes email through sendgrid with SES failover tags: - production - email routing: method: single channels: - email channels: email: providers: - sendgrid - ses providers: sendgrid: override: {} Minimal: summary: Create a minimal routing strategy value: name: Simple Email routing: method: single channels: - email /routing-strategies/{id}: get: description: Retrieve a routing strategy by ID. Returns the full entity including routing content and metadata. operationId: routingStrategies_retrieve tags: - Routing Strategies parameters: - name: id in: path description: Routing strategy ID (rs_ prefix). required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RoutingStrategyGetResponse' examples: FullStrategy: value: id: rs_01kx4h2jdafq8bk9amzvy6hbv0 name: Email via SendGrid description: Routes email through sendgrid with SES failover tags: - production - email routing: method: single channels: - email channels: email: providers: - sendgrid - ses providers: sendgrid: override: {} created: 1710000000000 creator: user_abc updated: 1710000000000 updater: user_def '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: StrategyNotFound: value: type: invalid_request_error message: Routing strategy rs_01kx4kepxgfq9ty3rersxgwk8x not found summary: Get Routing Strategy security: - BearerAuth: [] put: description: >- Replace a routing strategy. Full document replacement; the caller must send the complete desired state. Missing optional fields are cleared. operationId: routingStrategies_replace tags: - Routing Strategies parameters: - name: id in: path description: Routing strategy ID (rs_ prefix). required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RoutingStrategyGetResponse' examples: Example: value: id: rs_01kx4h2jdafq8bk9amzvy6hbv0 name: Example Name description: An example description. tags: - string routing: method: all channels: - string channels: channels_key: brand_id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag providers: - string routing_method: all if: string timeouts: provider: 1 channel: 1 override: {} metadata: utm: source: string medium: string campaign: string term: string content: string providers: providers_key: override: {} if: string timeouts: 1 metadata: utm: source: string medium: string campaign: string term: string content: string created: 1 creator: user_123 updated: 1 updater: user_123 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: ValidationError: value: type: invalid_request_error message: 'name: Required; routing: Required' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: StrategyNotFound: value: type: invalid_request_error message: Routing strategy rs_01kx4kepxgfq9ty3rersxgwk8x not found summary: Replace Routing Strategy security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RoutingStrategyReplaceRequest' examples: FullReplace: summary: Replace all fields value: name: Email via SendGrid v2 description: Updated routing with SES primary tags: - production - email - v2 routing: method: single channels: - email channels: email: providers: - ses - sendgrid providers: ses: override: {} delete: description: >- Archive a routing strategy. The strategy must not have associated notification templates. Unlink all templates before archiving. operationId: routingStrategies_archive tags: - Routing Strategies parameters: - name: id in: path description: Routing strategy ID (rs_ prefix). required: true schema: type: string responses: '204': description: Successfully archived. '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: StrategyNotFound: value: type: invalid_request_error message: Routing strategy rs_01kx4kepxgfq9ty3rersxgwk8x not found '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Conflict' examples: HasAssociatedTemplates: value: type: invalid_request_error message: >- Routing strategy rs_01kx4h2jdafq8bk9amzvy6hbv0 has associated templates and cannot be archived summary: Archive Routing Strategy security: - BearerAuth: [] /routing-strategies/{id}/notifications: get: description: >- List notification templates associated with a routing strategy. Includes template metadata only, not full content. operationId: routingStrategies_listNotifications tags: - Routing Strategies parameters: - name: id in: path description: Routing strategy ID (`rs_` prefix). required: true schema: type: string - name: cursor in: query description: Opaque pagination cursor from a previous response. Omit for the first page. required: false schema: type: string nullable: true - name: limit in: query description: Maximum number of results per page. Default 20, max 100. required: false schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: Associated notification templates retrieved. content: application/json: schema: $ref: '#/components/schemas/AssociatedNotificationListResponse' examples: WithResults: value: results: - id: nt_01kx4h2jdafq8bk9aftxak4b40 name: Welcome Email tags: - onboarding state: PUBLISHED created: 1710000000000 creator: user_abc updated: 1710000000000 updater: user_def paging: cursor: eyJway... more: true Empty: value: results: [] paging: more: false '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: StrategyNotFound: value: type: invalid_request_error message: Routing strategy rs_01kx4kepxgfq9ty3rersxgwk8x not found summary: List Associated Notifications security: - BearerAuth: [] /preferences/publish: post: description: >- Publish the workspace's preferences page. Takes a snapshot of every workspace preference with its topics under a new published version, making the current state visible on the hosted preferences page (non-draft). operationId: workspacePreferences_publish tags: - Workspace Preferences parameters: [] requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/PublishPreferencesRequest' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PublishPreferencesResponse' examples: Example: value: page_id: page_default published_at: '2024-01-15T10:30:00.000Z' published_by: user_123 published_version: 1 preview_url: https://example.com summary: Publish Preferences Page security: - BearerAuth: [] /preferences/sections: get: description: >- List the workspace's preferences. Each workspace preference embeds its topics. Scoped to the workspace of the API key. operationId: workspacePreferences_list tags: - Workspace Preferences parameters: [] responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceListResponse' examples: Example: value: results: - id: ps_01kx4h2jdafq8bk9b6w3knrezh name: Account Notifications routing_options: - direct_message has_custom_routing: true created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 topics: - id: pt_01kx4h2jdafq8bk99mj9q2gsa2 name: Product Updates default_status: OPTED_OUT routing_options: - direct_message allowed_preferences: - snooze include_unsubscribe_header: true topic_data: {} created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 summary: List Workspace Preferences security: - BearerAuth: [] post: description: >- Create a workspace preference. The workspace preference id is generated and returned. Topics are created inside a workspace preference via POST /preferences/sections/{section_id}/topics. operationId: workspacePreferences_create tags: - Workspace Preferences parameters: [] responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceGetResponse' examples: Example: value: id: ps_01kx4h2jdafq8bk9b6w3knrezh name: Account Notifications routing_options: - direct_message has_custom_routing: true created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 topics: - id: pt_01kx4h2jdafq8bk99mj9q2gsa2 name: Product Updates default_status: OPTED_OUT routing_options: - direct_message allowed_preferences: - snooze include_unsubscribe_header: true topic_data: {} created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Create Workspace Preference security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceCreateRequest' examples: Minimal: value: name: Account Notifications Full: value: name: Account Notifications routing_options: - email - push has_custom_routing: true /preferences/sections/{section_id}: get: description: Retrieve a workspace preference by id, including its topics. operationId: workspacePreferences_retrieve tags: - Workspace Preferences parameters: - name: section_id in: path description: Id of the workspace preference. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceGetResponse' examples: Example: value: id: ps_01kx4h2jdafq8bk9b6w3knrezh name: Account Notifications routing_options: - direct_message has_custom_routing: true created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 topics: - id: pt_01kx4h2jdafq8bk99mj9q2gsa2 name: Product Updates default_status: OPTED_OUT routing_options: - direct_message allowed_preferences: - snooze include_unsubscribe_header: true topic_data: {} created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: WorkspacePreferenceNotFound: value: type: invalid_request_error message: Workspace preference not found summary: Get Workspace Preference security: - BearerAuth: [] put: description: >- Replace a workspace preference. Full document replacement; missing optional fields are cleared. Topics attached to the workspace preference are unaffected. operationId: workspacePreferences_replace tags: - Workspace Preferences parameters: - name: section_id in: path description: Id of the workspace preference. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceGetResponse' examples: Example: value: id: ps_01kx4h2jdafq8bk9b6w3knrezh name: Account Notifications routing_options: - direct_message has_custom_routing: true created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 topics: - id: pt_01kx4h2jdafq8bk99mj9q2gsa2 name: Product Updates default_status: OPTED_OUT routing_options: - direct_message allowed_preferences: - snooze include_unsubscribe_header: true topic_data: {} created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Replace Workspace Preference security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceReplaceRequest' delete: description: >- Archive a workspace preference. The workspace preference must be empty: delete its topics first, otherwise the request fails with 409. operationId: workspacePreferences_archive tags: - Workspace Preferences parameters: - name: section_id in: path description: Id of the workspace preference. required: true schema: type: string responses: '204': description: Successfully archived. '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Conflict' examples: WorkspacePreferenceNotEmpty: value: type: invalid_request_error message: Cannot delete a workspace preference that still contains topics summary: Archive Workspace Preference security: - BearerAuth: [] /preferences/sections/{section_id}/topics: get: description: List the topics in a workspace preference. operationId: workspacePreferences_topics_list tags: - Workspace Preferences parameters: - name: section_id in: path description: Id of the workspace preference. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceTopicListResponse' examples: Example: value: results: - id: pt_01kx4h2jdafq8bk99mj9q2gsa2 name: Product Updates default_status: OPTED_OUT routing_options: - direct_message allowed_preferences: - snooze include_unsubscribe_header: true topic_data: {} created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: List Topics in Section security: - BearerAuth: [] post: description: >- Create a subscription preference topic inside a workspace preference. Fails with 404 if the workspace preference does not exist. The topic id is generated and returned. operationId: workspacePreferences_topics_create tags: - Workspace Preferences parameters: - name: section_id in: path description: Id of the workspace preference to create the topic in. required: true schema: type: string responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceTopicGetResponse' examples: Example: value: id: pt_01kx4h2jdafq8bk99mj9q2gsa2 name: Product Updates default_status: OPTED_OUT routing_options: - direct_message allowed_preferences: - snooze include_unsubscribe_header: true topic_data: {} created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: WorkspacePreferenceNotFound: value: type: invalid_request_error message: Workspace preference not found summary: Create Topic in Section security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceTopicCreateRequest' examples: Minimal: value: name: Marketing default_status: OPTED_OUT Full: value: name: Product Updates default_status: OPTED_IN routing_options: - email - push allowed_preferences: - channel_preferences - snooze include_unsubscribe_header: true /preferences/sections/{section_id}/topics/{topic_id}: get: description: >- Retrieve a topic within a workspace preference. Returns 404 if the workspace preference does not exist, the topic does not exist, or the topic belongs to a different workspace preference. operationId: workspacePreferences_topics_retrieve tags: - Workspace Preferences parameters: - name: section_id in: path description: Id of the workspace preference. required: true schema: type: string - name: topic_id in: path description: Id of the subscription preference topic. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceTopicGetResponse' examples: Example: value: id: pt_01kx4h2jdafq8bk99mj9q2gsa2 name: Product Updates default_status: OPTED_OUT routing_options: - direct_message allowed_preferences: - snooze include_unsubscribe_header: true topic_data: {} created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Get Topic in Section security: - BearerAuth: [] put: description: >- Replace a topic within a workspace preference. Full document replacement; missing optional fields are cleared. Same 404 rules as GET. operationId: workspacePreferences_topics_replace tags: - Workspace Preferences parameters: - name: section_id in: path description: Id of the workspace preference. required: true schema: type: string - name: topic_id in: path description: Id of the subscription preference topic. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceTopicGetResponse' examples: Example: value: id: pt_01kx4h2jdafq8bk99mj9q2gsa2 name: Product Updates default_status: OPTED_OUT routing_options: - direct_message allowed_preferences: - snooze include_unsubscribe_header: true topic_data: {} created: '2024-01-15T10:30:00.000Z' creator: user_123 updated: '2024-01-15T10:30:00.000Z' updater: user_123 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Replace Topic in Section security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkspacePreferenceTopicReplaceRequest' delete: description: Archive a topic and remove it from its workspace preference. Same 404 rules as GET. operationId: workspacePreferences_topics_archive tags: - Workspace Preferences parameters: - name: section_id in: path description: Id of the workspace preference. required: true schema: type: string - name: topic_id in: path description: Id of the subscription preference topic. required: true schema: type: string responses: '204': description: Successfully archived. '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Archive Topic in Section security: - BearerAuth: [] /providers: get: description: List configured provider integrations for the current workspace. Supports cursor-based pagination. operationId: providers_list tags: - Providers parameters: - name: cursor in: query description: Opaque cursor for fetching the next page. required: false schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ProvidersListResponse' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true results: - id: pc_01kx4h2jdafq8bk9arsty8hr35 title: Example Name provider: string alias: string settings: {} created: 1 updated: 1 summary: List providers security: - BearerAuth: [] post: description: >- Create a new provider configuration. The `provider` field must be a known Courier provider key (see catalog). operationId: providers_create tags: - Providers parameters: [] responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Provider' examples: Example: value: id: pc_01kx4h2jdafq8bk9arsty8hr35 title: Example Name provider: string alias: string settings: {} created: 1 updated: 1 '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error summary: Create a provider security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProvidersCreateRequest' /providers/catalog: get: description: >- Returns the catalog of available provider types with their display names, descriptions, and configuration schema fields (snake_case, with `type` and `required`). Providers with no configurable schema return only `provider`, `name`, and `description`. operationId: providers_catalog tags: - Providers parameters: - name: keys in: query description: Comma-separated provider keys to filter by (e.g. `sendgrid,twilio`). required: false schema: type: string - name: name in: query description: Case-insensitive substring match against the provider display name. required: false schema: type: string - name: channel in: query description: >- Exact match (case-insensitive) against the provider channel taxonomy (e.g. `email`, `sms`, `push`). required: false schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ProvidersCatalogResponse' examples: Example: value: paging: cursor: MTpFWUNFRkRRN0c1WERTRTU2 more: true results: - provider: string name: Example Name description: An example description. channel: string settings: settings_key: type: string required: true values: - string summary: List available provider types security: - BearerAuth: [] /providers/{id}: get: description: Fetch a single provider configuration by ID. operationId: providers_retrieve tags: - Providers parameters: - name: id in: path description: A unique identifier of the provider configuration. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Provider' examples: Example: value: id: pc_01kx4h2jdafq8bk9arsty8hr35 title: Example Name provider: string alias: string settings: {} created: 1 updated: 1 '404': description: '' content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Get a provider security: - BearerAuth: [] put: description: >- Replace an existing provider configuration. The `provider` key is required and determines which provider-specific settings schema is applied. All other fields are optional — omitted fields are cleared from the stored configuration (this is a full replacement, not a partial merge). Changing the provider type for an existing configuration is not supported. operationId: providers_update tags: - Providers parameters: - name: id in: path description: A unique identifier of the provider configuration to update. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Provider' examples: Example: value: id: pc_01kx4h2jdafq8bk9arsty8hr35 title: Example Name provider: string alias: string settings: {} created: 1 updated: 1 '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error '404': description: '' content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: Example: value: message: Example message text type: invalid_request_error summary: Update a provider security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProvidersUpdateRequest' delete: description: >- Delete a provider configuration. Returns 409 if the provider is still referenced by routing or notifications. operationId: providers_delete tags: - Providers parameters: - name: id in: path description: A unique identifier of the provider configuration to delete. required: true schema: type: string responses: '204': description: Provider successfully deleted. '409': description: '' content: application/json: schema: $ref: '#/components/schemas/Conflict' examples: Example: value: message: Example message text type: invalid_request_error summary: Delete a provider security: - BearerAuth: [] components: schemas: SendMessageResponse: title: SendMessageResponse type: object properties: requestId: type: string description: >- A successful call to `POST /send` returns a `202` status code along with a `requestId` in the response body. For single-recipient requests, the `requestId` is the derived message_id. For multiple recipients, Courier assigns a unique message_id to each derived message. example: 1-69f561d3-7ad9d453fb6a7012efc2c5ad required: - requestId ResendMessageResponse: title: ResendMessageResponse type: object properties: messageId: type: string description: >- The new message id for the resent message. It is distinct from the id of the original message that was resent. example: 1-5e2b2615-05efbb3acab9172f88dd3f6f required: - messageId Message: title: Message oneOf: - $ref: '#/components/schemas/ContentMessage' ContentMessage: title: ContentMessage type: object description: >- The message property has the following primary top-level properties. They define the destination and content of the message. properties: content: $ref: '#/components/schemas/Content' description: Describes content that will work for email, inbox, push, chat, or any channel id. allOf: - $ref: '#/components/schemas/BaseMessage' - $ref: '#/components/schemas/BaseMessageSendTo' Content: title: Content oneOf: - $ref: '#/components/schemas/ElementalContentSugar' - $ref: '#/components/schemas/ElementalContent' ElementalContentSugar: title: ElementalContentSugar type: object description: Syntactic sugar to provide a fast shorthand for Courier Elemental Blocks. properties: title: type: string description: Title/subject displayed by supported channels. body: type: string description: The text content displayed in the notification. required: - title - body ElementalContent: title: ElementalContent type: object properties: version: type: string description: For example, "2022-01-01" elements: type: array items: $ref: '#/components/schemas/ElementalNode' required: - version - elements ElementalNode: title: ElementalNode oneOf: - type: object allOf: - type: object properties: type: type: string enum: - text - $ref: '#/components/schemas/ElementalTextNode' required: - type - type: object allOf: - type: object properties: type: type: string enum: - meta - $ref: '#/components/schemas/ElementalMetaNode' required: - type - type: object allOf: - type: object properties: type: type: string enum: - channel - $ref: '#/components/schemas/ElementalChannelNode' required: - type - channel - type: object allOf: - type: object properties: type: type: string enum: - image - $ref: '#/components/schemas/ElementalImageNode' required: - type - type: object allOf: - type: object properties: type: type: string enum: - action - $ref: '#/components/schemas/ElementalActionNode' required: - type - type: object allOf: - type: object properties: type: type: string enum: - divider - $ref: '#/components/schemas/ElementalDividerNode' required: - type - type: object allOf: - type: object properties: type: type: string enum: - quote - $ref: '#/components/schemas/ElementalQuoteNode' required: - type - type: object allOf: - type: object properties: type: type: string enum: - html - $ref: '#/components/schemas/ElementalHtmlNode' required: - type ElementalTextNode: title: ElementalTextNode type: object description: Represents a body of text to be rendered inside of the notification. properties: content: type: string description: |- The text content displayed in the notification. Either this field must be specified, or the elements field align: $ref: '#/components/schemas/TextAlign' description: Text alignment. text_style: $ref: '#/components/schemas/TextStyle' nullable: true description: Allows the text to be rendered as a heading level. color: type: string nullable: true description: Specifies the color of text. Can be any valid css color value bold: type: string nullable: true description: Apply bold to the text italic: type: string nullable: true description: Apply italics to the text strikethrough: type: string nullable: true description: Apply a strike through the text underline: type: string nullable: true description: Apply an underline to the text locales: $ref: '#/components/schemas/Locales' nullable: true description: >- Region specific content. See [locales docs](https://www.courier.com/docs/platform/content/elemental/locales/) for more details. format: type: string enum: - markdown nullable: true required: - content - align allOf: - $ref: '#/components/schemas/ElementalBaseNode' ElementalMetaNode: title: ElementalMetaNode type: object description: |- The meta element contains information describing the notification that may be used by a particular channel or provider. One important field is the title field which will be used as the title for channels that support it. properties: title: type: string nullable: true description: The title to be displayed by supported channels. For example, the email subject. allOf: - $ref: '#/components/schemas/ElementalBaseNode' ElementalChannelNode: title: ElementalChannelNode type: object description: >- The channel element allows a notification to be customized based on which channel it is sent through. For example, you may want to display a detailed message when the notification is sent through email, and a more concise message in a push notification. Channel elements are only valid as top-level elements; you cannot nest channel elements. If there is a channel element specified at the top-level of the document, all sibling elements must be channel elements. Note: As an alternative, most elements support a `channel` property. Which allows you to selectively display an individual element on a per channel basis. See the [control flow docs](https://www.courier.com/docs/platform/content/elemental/control-flow/) for more details. properties: channel: type: string example: email description: |- The channel the contents of this element should be applied to. Can be `email`, `push`, `direct_message`, `sms` or a provider such as slack raw: type: object additionalProperties: true nullable: true description: Raw data to apply to the channel. If `elements` has not been specified, `raw` is required. allOf: - $ref: '#/components/schemas/ElementalBaseNode' ElementalImageNode: title: ElementalImageNode type: object description: Used to embed an image into the notification. properties: src: type: string description: The source of the image. href: type: string nullable: true description: A URL to link to when the image is clicked. align: $ref: '#/components/schemas/IAlignment' nullable: true description: The alignment of the image. altText: type: string nullable: true description: Alternate text for the image. width: type: string nullable: true description: CSS width properties to apply to the image. For example, 50px border_color: type: string nullable: true description: CSS border color applied to the image. For example, `#ccc` border_size: type: string nullable: true description: CSS border width applied to the image. For example, `1px` padding: type: string nullable: true description: CSS padding applied around the image. For example, `10px` required: - src allOf: - $ref: '#/components/schemas/ElementalBaseNode' ElementalActionNode: title: ElementalActionNode type: object description: Allows the user to execute an action. Can be a button or a link. properties: content: type: string description: The text content of the action shown to the user. href: type: string description: The target URL of the action. action_id: type: string nullable: true description: A unique id used to identify the action when it is executed. align: nullable: true description: The alignment of the action button. Defaults to "center". allOf: - $ref: '#/components/schemas/IAlignment' background_color: type: string nullable: true description: The background color of the action button. border_radius: type: string nullable: true description: CSS border-radius applied to the action button. For example, `4px` border_size: type: string nullable: true description: CSS border width applied to the action button. For example, `1px` font_size: type: string nullable: true description: CSS font-size applied to the action button label. For example, `14px` padding: type: string nullable: true description: CSS padding applied to the action button. For example, `8px 16px` disable_tracking: type: boolean nullable: true description: >- When true, the action's href is not rewritten for click-through tracking, even when click-through tracking is enabled for the workspace. style: nullable: true description: Defaults to `button`. allOf: - $ref: '#/components/schemas/IActionButtonStyle' locales: description: >- Region specific content. See [locales docs](https://www.courier.com/docs/platform/content/elemental/locales/) for more details. allOf: - $ref: '#/components/schemas/Locales' required: - content - href - locales allOf: - $ref: '#/components/schemas/ElementalBaseNode' ElementalDividerNode: title: ElementalDividerNode type: object description: Renders a dividing line between elements. properties: color: type: string nullable: true description: The CSS color to render the line with. For example, `#fff` allOf: - $ref: '#/components/schemas/ElementalBaseNode' ElementalQuoteNode: title: ElementalQuoteNode type: object description: Renders a quote block. properties: content: type: string description: The text value of the quote. align: $ref: '#/components/schemas/IAlignment' nullable: true description: Alignment of the quote. borderColor: type: string nullable: true description: CSS border color property. For example, `#fff` text_style: $ref: '#/components/schemas/TextStyle' locales: $ref: '#/components/schemas/Locales' description: >- Region specific content. See [locales docs](https://www.courier.com/docs/platform/content/elemental/locales/) for more details. required: - content - text_style - locales allOf: - $ref: '#/components/schemas/ElementalBaseNode' ElementalHtmlNode: title: ElementalHtmlNode type: object description: >- Raw HTML string inside an Elemental document. When rendering a message, this node is turned into output only for the email channel; for other channels it produces no blocks. properties: content: type: string description: Raw HTML string to render inside the notification. locales: $ref: '#/components/schemas/Locales' nullable: true description: >- Region-specific `content` overrides. See [locales docs](https://www.courier.com/docs/platform/content/elemental/locales/) for more details. required: - content allOf: - $ref: '#/components/schemas/ElementalBaseNode' TextAlign: title: TextAlign type: string enum: - left - center - right TextStyle: title: TextStyle type: string enum: - text - h1 - h2 - subtext Locales: title: Locales type: object additionalProperties: $ref: '#/components/schemas/Locale' nullable: true Locale: title: Locale type: object properties: content: type: string required: - content IAlignment: title: IAlignment type: string enum: - center - left - right - full ElementalBaseNode: title: ElementalBaseNode type: object properties: channels: type: array items: type: string nullable: true ref: type: string nullable: true if: type: string nullable: true loop: type: string nullable: true IActionButtonStyle: title: IActionButtonStyle type: string enum: - button - link BaseMessage: title: BaseMessage type: object properties: template: type: string nullable: true data: $ref: '#/components/schemas/MessageData' nullable: true brand_id: type: string nullable: true channels: $ref: '#/components/schemas/MessageChannels' nullable: true description: >- Define run-time configuration for channels. Valid ChannelId's: email, sms, push, inbox, direct_message, banner, webhook. context: $ref: '#/components/schemas/MessageContext' nullable: true metadata: $ref: '#/components/schemas/MessageMetadata' nullable: true preferences: $ref: '#/components/schemas/MessagePreferences' nullable: true providers: $ref: '#/components/schemas/MessageProviders' nullable: true routing: $ref: '#/components/schemas/Routing' nullable: true timeout: $ref: '#/components/schemas/Timeout' nullable: true delay: $ref: '#/components/schemas/Delay' nullable: true expiry: $ref: '#/components/schemas/Expiry' nullable: true BaseMessageSendTo: title: BaseMessageSendTo type: object properties: to: $ref: '#/components/schemas/MessageRecipient' nullable: true description: The recipient or a list of recipients of the message Audience: title: Audience type: object properties: id: type: string description: A unique identifier representing the audience_id name: type: string description: The name of the audience description: type: string description: A description of the audience operator: $ref: '#/components/schemas/LogicalOperator' description: >- The logical operator (AND/OR) combining the top-level `filter.filters`. Convenience alias for `filter.operator`. filter: $ref: '#/components/schemas/AudienceFilterConfig' nullable: true created_at: type: string updated_at: type: string required: - id - name - description - created_at - updated_at AudienceUpdateResponse: title: AudienceUpdateResponse type: object properties: audience: $ref: '#/components/schemas/Audience' required: - audience MessageRecipient: title: MessageRecipient description: The recipient of a message. Can be a single recipient or an array of recipients. oneOf: - $ref: '#/components/schemas/Recipient' - type: array items: $ref: '#/components/schemas/Recipient' Recipient: title: Recipient description: >- A single recipient of the message. Choose one of the following types based on how you want to identify the recipient: - **User**: Send to a specific user by user_id, email, or phone number - **Audience**: Send to all users in an audience - **List**: Send to all users in a list - **List Pattern**: Send to users in lists matching a pattern - **Slack**: Send via Slack (channel, email, or user_id) - **MS Teams**: Send via Microsoft Teams - **PagerDuty**: Send via PagerDuty - **Webhook**: Send via webhook oneOf: - $ref: '#/components/schemas/UserRecipient' - $ref: '#/components/schemas/AudienceRecipient' - $ref: '#/components/schemas/ListRecipient' - $ref: '#/components/schemas/ListPatternRecipient' - $ref: '#/components/schemas/SlackRecipient' - $ref: '#/components/schemas/MsTeamsRecipient' - $ref: '#/components/schemas/PagerdutyRecipient' - $ref: '#/components/schemas/WebhookRecipient' discriminator: propertyName: _type mapping: user: '#/components/schemas/UserRecipient' audience: '#/components/schemas/AudienceRecipient' list: '#/components/schemas/ListRecipient' list_pattern: '#/components/schemas/ListPatternRecipient' slack: '#/components/schemas/SlackRecipient' ms_teams: '#/components/schemas/MsTeamsRecipient' pagerduty: '#/components/schemas/PagerdutyRecipient' webhook: '#/components/schemas/WebhookRecipient' UserRecipient: title: User Recipient description: Send to a specific user by user_id, email, phone_number, or list_id type: object properties: user_id: type: string nullable: true description: The user's unique identifier. Typically, this will match the user id of a user in your system. account_id: type: string nullable: true description: Deprecated - Use `tenant_id` instead. context: $ref: '#/components/schemas/MessageContext' nullable: true description: Context such as tenant_id to send the notification with. data: $ref: '#/components/schemas/MessageData' nullable: true email: type: string nullable: true description: The user's email address. locale: type: string nullable: true description: The user's preferred ISO 639-1 language code. phone_number: type: string nullable: true description: The user's phone number. list_id: type: string nullable: true description: The id of the list to send the message to. preferences: $ref: '#/components/schemas/ProfilePreferences' nullable: true tenant_id: type: string nullable: true description: The id of the tenant the user is associated with. allOf: - $ref: '#/components/schemas/UserRecipientType' UserRecipientType: title: UserRecipientType type: object properties: {} AudienceRecipient: title: Audience Recipient description: Send to all users in an audience type: object properties: audience_id: type: string description: >- A unique identifier associated with an Audience. A message will be sent to each user in the audience. data: $ref: '#/components/schemas/MessageData' nullable: true filters: type: array items: $ref: '#/components/schemas/AudienceFilter' nullable: true required: - audience_id ListRecipient: title: List Recipient description: Send to all users in a specific list type: object properties: list_id: type: string nullable: true data: $ref: '#/components/schemas/MessageData' nullable: true filters: type: array items: $ref: '#/components/schemas/ListFilter' nullable: true ListPatternRecipient: title: List Pattern Recipient description: Send to users in lists matching a pattern type: object properties: list_pattern: type: string nullable: true data: $ref: '#/components/schemas/MessageData' nullable: true SlackRecipient: title: Slack Recipient description: Send via Slack (channel, email, or user_id) type: object properties: slack: $ref: '#/components/schemas/Slack' required: - slack MsTeamsRecipient: title: MS Teams Recipient description: Send via Microsoft Teams type: object properties: ms_teams: $ref: '#/components/schemas/MsTeams' required: - ms_teams WebhookRecipient: title: Webhook Recipient description: Send via webhook type: object properties: webhook: $ref: '#/components/schemas/WebhookProfile' required: - webhook PagerdutyRecipient: title: PagerDuty Recipient description: Send via PagerDuty type: object properties: pagerduty: $ref: '#/components/schemas/Pagerduty' required: - pagerduty MessageContext: title: MessageContext type: object properties: tenant_id: type: string nullable: true description: Tenant id used to load brand/default preferences/context. MessageData: title: MessageData type: object additionalProperties: true ProfilePreferences: title: ProfilePreferences type: object properties: categories: $ref: '#/components/schemas/Preferences' nullable: true notifications: $ref: '#/components/schemas/Preferences' templateId: type: string nullable: true required: - notifications Preferences: title: Preferences type: object additionalProperties: $ref: '#/components/schemas/Preference' Preference: title: Preference type: object properties: status: $ref: '#/components/schemas/PreferenceStatus' rules: type: array items: $ref: '#/components/schemas/Rule' nullable: true channel_preferences: type: array items: $ref: '#/components/schemas/ChannelPreference' nullable: true source: $ref: '#/components/schemas/ChannelSource' nullable: true required: - status PreferenceStatus: title: PreferenceStatus type: string enum: - OPTED_IN - OPTED_OUT - REQUIRED Rule: title: Rule type: object properties: start: type: string nullable: true until: type: string required: - until ChannelPreference: title: ChannelPreference type: object properties: channel: $ref: '#/components/schemas/ChannelClassification' required: - channel ChannelClassification: title: ChannelClassification type: string enum: - direct_message - email - push - sms - webhook - inbox ChannelSource: title: ChannelSource type: string enum: - subscription - list - recipient AudienceFilter: title: AudienceFilter type: object properties: operator: type: string enum: - MEMBER_OF description: Send to users only if they are member of the account path: type: string enum: - account_id value: type: string required: - operator - path - value ListFilter: title: ListFilter type: object properties: operator: type: string enum: - MEMBER_OF description: Send to users only if they are member of the account path: type: string enum: - account_id value: type: string required: - operator - path - value Routing: title: Routing type: object description: Customize which channels/providers Courier may deliver the message through. properties: method: $ref: '#/components/schemas/RoutingMethod' channels: type: array items: $ref: '#/components/schemas/MessageRoutingChannel' description: A list of channels or providers (or nested routing rules). required: - method - channels RoutingMethod: title: RoutingMethod type: string enum: - all - single MessageRoutingChannel: title: MessageRoutingChannel oneOf: - type: string - $ref: '#/components/schemas/MessageRouting' MessageRouting: title: MessageRouting type: object properties: method: $ref: '#/components/schemas/MessageRoutingMethod' channels: type: array items: $ref: '#/components/schemas/MessageRoutingChannel' required: - method - channels MessageRoutingMethod: title: MessageRoutingMethod type: string enum: - all - single MessageChannels: title: MessageChannels type: object additionalProperties: $ref: '#/components/schemas/Channel' Channel: title: Channel type: object properties: brand_id: type: string nullable: true description: Brand id used for rendering. providers: type: array items: type: string nullable: true description: Providers enabled for this channel. routing_method: $ref: '#/components/schemas/RoutingMethod' nullable: true description: Defaults to `single`. if: type: string nullable: true description: JS conditional with access to data/profile. timeouts: $ref: '#/components/schemas/Timeouts' nullable: true override: type: object additionalProperties: true nullable: true description: Channel specific overrides. metadata: $ref: '#/components/schemas/ChannelMetadata' nullable: true x-stainless-naming: csharp: type_name: MessageChannel ChannelMetadata: title: ChannelMetadata type: object properties: utm: $ref: '#/components/schemas/UTM' nullable: true MessageProviders: title: MessageProviders type: object additionalProperties: $ref: '#/components/schemas/MessageProvidersType' MessageProvidersType: title: MessageProvidersType type: object properties: override: type: object additionalProperties: true nullable: true description: Provider-specific overrides. if: type: string nullable: true description: JS conditional with access to data/profile. timeouts: type: integer nullable: true metadata: $ref: '#/components/schemas/Metadata' nullable: true Timeout: title: Timeout type: object properties: provider: type: object additionalProperties: type: integer nullable: true channel: type: object additionalProperties: type: integer nullable: true message: type: integer nullable: true escalation: type: integer nullable: true criteria: $ref: '#/components/schemas/Criteria' nullable: true Criteria: title: Criteria type: string enum: - no-escalation - delivered - viewed - engaged Timeouts: title: Timeouts type: object properties: provider: type: integer nullable: true channel: type: integer nullable: true x-stainless-naming: csharp: type_name: ChannelTimeouts Delay: title: Delay type: object properties: duration: type: integer nullable: true description: The duration of the delay in milliseconds. until: type: string nullable: true description: ISO 8601 timestamp or opening_hours-like format. timezone: type: string nullable: true description: >- IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Used when resolving opening hours expressions. Takes precedence over user profile timezone settings. Expiry: title: Expiry type: object properties: expires_at: type: string nullable: true description: Epoch or ISO8601 timestamp with timezone. expires_in: $ref: '#/components/schemas/ExpiresInType' description: Duration in ms or ISO8601 duration (e.g. P1DT4H). required: - expires_in ExpiresInType: title: ExpiresInType oneOf: - type: string - type: integer MessageMetadata: title: MessageMetadata type: object properties: event: type: string nullable: true tags: type: array items: type: string nullable: true utm: $ref: '#/components/schemas/UTM' nullable: true trace_id: type: string nullable: true UTM: title: UTM type: object properties: source: type: string nullable: true medium: type: string nullable: true campaign: type: string nullable: true term: type: string nullable: true content: type: string nullable: true MessagePreferences: title: MessagePreferences type: object properties: subscription_topic_id: type: string description: The subscription topic to apply to the message. required: - subscription_topic_id Metadata: title: Metadata type: object properties: utm: $ref: '#/components/schemas/UTM' nullable: true x-stainless-naming: csharp: type_name: ProviderMetadata Slack: title: Slack oneOf: - $ref: '#/components/schemas/SendToSlackChannel' - $ref: '#/components/schemas/SendToSlackEmail' - $ref: '#/components/schemas/SendToSlackUserId' SlackBaseProperties: title: SlackBaseProperties type: object properties: access_token: type: string required: - access_token SendToSlackChannel: title: SendToSlackChannel type: object properties: access_token: type: string channel: type: string required: - access_token - channel SendToSlackEmail: title: SendToSlackEmail type: object properties: access_token: type: string email: type: string required: - access_token - email SendToSlackUserId: title: SendToSlackUserId type: object properties: access_token: type: string user_id: type: string required: - access_token - user_id MsTeams: title: MsTeams oneOf: - $ref: '#/components/schemas/SendToMsTeamsUserId' - $ref: '#/components/schemas/SendToMsTeamsEmail' - $ref: '#/components/schemas/SendToMsTeamsChannelId' - $ref: '#/components/schemas/SendToMsTeamsConversationId' - $ref: '#/components/schemas/SendToMsTeamsChannelName' MsTeamsBaseProperties: title: MsTeamsBaseProperties type: object properties: tenant_id: type: string service_url: type: string required: - tenant_id - service_url SendToMsTeamsUserId: title: SendToMsTeamsUserId type: object properties: tenant_id: type: string service_url: type: string user_id: type: string required: - tenant_id - service_url - user_id SendToMsTeamsEmail: title: SendToMsTeamsEmail type: object properties: tenant_id: type: string service_url: type: string email: type: string required: - tenant_id - service_url - email SendToMsTeamsConversationId: title: SendToMsTeamsConversationId type: object properties: tenant_id: type: string service_url: type: string conversation_id: type: string required: - tenant_id - service_url - conversation_id SendToMsTeamsChannelId: title: SendToMsTeamsChannelId type: object properties: tenant_id: type: string service_url: type: string channel_id: type: string required: - tenant_id - service_url - channel_id SendToMsTeamsChannelName: title: SendToMsTeamsChannelName type: object properties: tenant_id: type: string service_url: type: string channel_name: type: string team_id: type: string required: - tenant_id - service_url - channel_name - team_id Pagerduty: title: Pagerduty type: object properties: routing_key: type: string nullable: true event_action: type: string nullable: true severity: type: string nullable: true source: type: string nullable: true WebhookProfile: title: WebhookProfile type: object properties: url: type: string description: The URL to send the webhook request to. method: $ref: '#/components/schemas/WebhookMethod' nullable: true description: The HTTP method to use for the webhook request. Defaults to POST if not specified. headers: type: object additionalProperties: type: string nullable: true description: Custom headers to include in the webhook request. authentication: $ref: '#/components/schemas/WebhookAuthentication' nullable: true description: Authentication configuration for the webhook request. profile: $ref: '#/components/schemas/WebhookProfileType' nullable: true description: >- Specifies what profile information is included in the request payload. Defaults to 'limited' if not specified. required: - url WebhookMethod: title: WebhookMethod type: string enum: - POST - PUT WebhookAuthentication: title: WebhookAuthentication type: object properties: mode: $ref: '#/components/schemas/WebhookAuthMode' description: The authentication mode to use. Defaults to 'none' if not specified. username: type: string nullable: true description: Username for basic authentication. password: type: string nullable: true description: Password for basic authentication. token: type: string nullable: true description: Token for bearer authentication. required: - mode WebhookAuthMode: title: WebhookAuthMode type: string enum: - none - basic - bearer WebhookProfileType: title: WebhookProfileType type: string enum: - limited - expanded UserProfile: title: UserProfile type: object properties: address: $ref: '#/components/schemas/Address' nullable: true birthdate: type: string nullable: true email: type: string nullable: true email_verified: type: boolean nullable: true family_name: type: string nullable: true gender: type: string nullable: true given_name: type: string nullable: true locale: type: string nullable: true middle_name: type: string nullable: true name: type: string nullable: true nickname: type: string nullable: true phone_number: type: string nullable: true phone_number_verified: type: boolean nullable: true picture: type: string nullable: true preferred_name: type: string nullable: true profile: type: string nullable: true sub: type: string nullable: true updated_at: type: string nullable: true website: type: string nullable: true zoneinfo: type: string nullable: true custom: type: object additionalProperties: true nullable: true description: >- A free form object. Due to a limitation of the API Explorer, you can only enter string key/values below, but this API accepts more complex object structures. airship: $ref: '#/components/schemas/AirshipProfile' nullable: true apn: type: string nullable: true target_arn: type: string nullable: true discord: $ref: '#/components/schemas/Discord' nullable: true expo: $ref: '#/components/schemas/Expo' nullable: true facebookPSID: type: string nullable: true firebaseToken: $ref: '#/components/schemas/UserProfileFirebaseToken' nullable: true intercom: $ref: '#/components/schemas/Intercom' nullable: true slack: $ref: '#/components/schemas/Slack' nullable: true ms_teams: $ref: '#/components/schemas/MsTeams' nullable: true UserProfileFirebaseToken: title: UserProfileFirebaseToken oneOf: - type: string - type: array items: type: string AirshipProfile: title: AirshipProfile type: object properties: audience: $ref: '#/components/schemas/AirshipProfileAudience' device_types: type: array items: $ref: '#/components/schemas/DeviceType' required: - audience - device_types AirshipProfileAudience: title: AirshipProfileAudience type: object properties: named_user: type: string required: - named_user DeviceType: title: DeviceType type: string Discord: title: Discord oneOf: - $ref: '#/components/schemas/SendToChannel' - $ref: '#/components/schemas/SendDirectMessage' SendToChannel: title: SendToChannel type: object properties: channel_id: type: string required: - channel_id SendDirectMessage: title: SendDirectMessage type: object properties: user_id: type: string required: - user_id Expo: title: Expo oneOf: - $ref: '#/components/schemas/Token' - $ref: '#/components/schemas/MultipleTokens' Token: title: Token type: object properties: token: type: string required: - token MultipleTokens: title: MultipleTokens type: object properties: tokens: type: array items: $ref: '#/components/schemas/Token' required: - tokens Intercom: title: Intercom type: object properties: from: type: string to: $ref: '#/components/schemas/IntercomRecipient' required: - from - to IntercomRecipient: title: IntercomRecipient type: object properties: id: type: string required: - id FilterConfig: title: FilterConfig type: object description: >- A filter rule that can be either a single condition (with path/value) or a nested group (with filters array). Use comparison operators (EQ, GT, etc.) for single conditions, and logical operators (AND, OR) for nested groups. properties: operator: type: string description: >- The operator for this filter. Use comparison operators (EQ, GT, LT, GTE, LTE, NEQ, EXISTS, INCLUDES, STARTS_WITH, ENDS_WITH, IS_BEFORE, IS_AFTER, OMIT) for single conditions, or logical operators (AND, OR) for nested filter groups. path: type: string description: >- The attribute path from the user profile to filter on. Required for single filter conditions, not used for nested filter groups. value: type: string description: >- The value to compare against. Required for single filter conditions, not used for nested filter groups. filters: type: array items: $ref: '#/components/schemas/FilterConfig' description: >- Nested filter rules to combine with AND/OR. Required for nested filter groups, not used for single filter conditions. required: - operator AudienceFilterConfig: title: AudienceFilterConfig type: object description: Filter configuration for audience membership containing an array of filter rules properties: operator: $ref: '#/components/schemas/LogicalOperator' description: >- The logical operator (AND/OR) combining the rules in `filters`. Required when `filters` contains more than one rule. If omitted, the top-level `operator` field on the request is used instead. filters: type: array items: $ref: '#/components/schemas/FilterConfig' description: Array of filter rules (single conditions or nested groups) required: - filters ComparisonOperator: title: ComparisonOperator type: string enum: - ENDS_WITH - EQ - EXISTS - GT - GTE - INCLUDES - IS_AFTER - IS_BEFORE - LT - LTE - NEQ - OMIT - STARTS_WITH LogicalOperator: title: LogicalOperator type: string enum: - AND - OR AudienceMember: title: AudienceMember type: object properties: added_at: type: string audience_id: type: string audience_version: type: integer member_id: type: string reason: type: string required: - added_at - audience_id - audience_version - member_id - reason AudienceListResponse: title: AudienceListResponse type: object properties: paging: $ref: '#/components/schemas/Paging' items: type: array items: $ref: '#/components/schemas/Audience' required: - paging - items AudienceMemberListResponse: title: AudienceMemberListResponse type: object properties: paging: $ref: '#/components/schemas/Paging' items: type: array items: $ref: '#/components/schemas/AudienceMember' required: - paging - items Paging: title: Paging type: object properties: cursor: type: string nullable: true more: type: boolean required: - more ListAuditEventsResponse: title: ListAuditEventsResponse type: object properties: paging: $ref: '#/components/schemas/Paging' results: type: array items: $ref: '#/components/schemas/AuditEvent' required: - paging - results AuditEvent: title: AuditEvent type: object properties: auditEventId: type: string actor: $ref: '#/components/schemas/Actor' target: type: string source: type: string timestamp: type: string type: type: string required: - auditEventId - actor - target - source - timestamp - type Actor: title: Actor type: object properties: id: type: string email: type: string nullable: true required: - id IssueTokenResponse: title: IssueTokenResponse type: object properties: token: type: string required: - token AutomationInvokeParams: title: AutomationInvokeParams type: object properties: brand: type: string nullable: true data: type: object additionalProperties: true nullable: true profile: type: object additionalProperties: true nullable: true recipient: type: string nullable: true template: type: string nullable: true required: - recipient AutomationAdHocInvokeParams: title: AutomationAdHocInvokeParams type: object properties: automation: $ref: '#/components/schemas/Automation' brand: type: string nullable: true data: type: object additionalProperties: true nullable: true profile: type: object additionalProperties: true nullable: true recipient: type: string nullable: true template: type: string nullable: true required: - automation Automation: title: Automation type: object properties: cancelation_token: type: string nullable: true steps: type: array items: $ref: '#/components/schemas/AutomationStep' required: - steps AutomationStep: title: AutomationStep oneOf: - $ref: '#/components/schemas/AutomationDelayStep' - $ref: '#/components/schemas/AutomationSendStep' - $ref: '#/components/schemas/AutomationSendListStep' - $ref: '#/components/schemas/AutomationUpdateProfileStep' - $ref: '#/components/schemas/AutomationCancelStep' - $ref: '#/components/schemas/AutomationFetchDataStep' - $ref: '#/components/schemas/AutomationInvokeStep' AutomationDelayStep: title: AutomationDelayStep type: object properties: action: type: string enum: - delay duration: type: string nullable: true until: type: string nullable: true required: - action AutomationSendStep: title: AutomationSendStep type: object properties: action: type: string enum: - send template: type: string nullable: true brand: type: string nullable: true data: type: object additionalProperties: true nullable: true profile: type: object additionalProperties: true nullable: true recipient: type: string nullable: true required: - action AutomationSendListStep: title: AutomationSendListStep type: object properties: action: type: string enum: - send-list list: type: string data: type: object additionalProperties: true nullable: true brand: type: string nullable: true required: - action - list AutomationUpdateProfileStep: title: AutomationUpdateProfileStep type: object properties: action: type: string enum: - update-profile recipient_id: type: string nullable: true merge: type: string enum: - none - overwrite - soft-merge - replace nullable: true profile: type: object additionalProperties: true required: - action - profile AutomationCancelStep: title: AutomationCancelStep type: object properties: action: type: string enum: - cancel cancelation_token: type: string required: - action - cancelation_token AutomationFetchDataStep: title: AutomationFetchDataStep type: object properties: action: type: string enum: - fetch-data webhook: $ref: '#/components/schemas/AutomationWebhookParams' merge_strategy: type: string enum: - replace - overwrite - soft-merge nullable: true required: - action - webhook AutomationWebhookParams: title: AutomationWebhookParams type: object properties: url: type: string method: type: string enum: - GET - POST - PUT - PATCH - DELETE headers: type: object additionalProperties: type: string nullable: true body: type: string nullable: true required: - url - method AutomationInvokeStep: title: AutomationInvokeStep type: object properties: action: type: string enum: - invoke template: type: string required: - action - template AutomationInvokeResponse: title: AutomationInvokeResponse type: object properties: runId: type: string required: - runId AutomationTemplate: title: AutomationTemplate type: object properties: name: type: string description: The name of the automation template. id: type: string description: The unique identifier of the automation template. version: type: string description: The version of the template published or drafted. enum: - published - draft createdAt: type: string format: date-time description: ISO 8601 timestamp when the template was created. updatedAt: type: string format: date-time description: ISO 8601 timestamp when the template was last updated. required: - name - id - version AutomationTemplateListResponse: title: AutomationTemplateListResponse type: object properties: templates: type: array items: $ref: '#/components/schemas/AutomationTemplate' cursor: type: string description: A cursor token for pagination. Present when there are more results available. JourneysInvokeRequest: title: JourneysInvokeRequest type: object description: >- Request body for invoking a journey. Requires either a user identifier or a profile with contact information. User identifiers can be provided via user_id field, or resolved from profile/data objects (user_id, userId, or anonymousId fields). properties: user_id: type: string description: >- A unique identifier for the user. If not provided, the system will attempt to resolve the user identifier from profile or data objects. profile: type: object additionalProperties: true description: >- Profile data for the user. Can contain contact information (email, phone_number), user identifiers (user_id, userId, anonymousId), or any custom profile fields. Profile fields are merged with any existing stored profile for the user. Include context.tenant_id to load a tenant-scoped profile for multi-tenant scenarios. data: type: object additionalProperties: true description: >- Data payload passed to the journey. The expected shape can be predefined using the schema builder in the journey editor. This data is available in journey steps for condition evaluation and template variable interpolation. Can also contain user identifiers (user_id, userId, anonymousId) if not provided elsewhere. JourneysInvokeResponse: title: JourneysInvokeResponse type: object properties: runId: type: string description: A unique identifier for the journey run that was created. required: - runId Journey: title: Journey type: object description: A journey template representing an automation workflow. properties: name: type: string description: The name of the journey. id: type: string description: The unique identifier of the journey. version: type: string description: The version of the journey (published or draft). enum: - published - draft createdAt: type: string format: date-time description: ISO 8601 timestamp when the journey was created. updatedAt: type: string format: date-time description: ISO 8601 timestamp when the journey was last updated. required: - name - id - version JourneysListResponse: title: JourneysListResponse type: object properties: templates: type: array items: $ref: '#/components/schemas/Journey' cursor: type: string description: A cursor token for pagination. Present when there are more results available. CreateJourneyRequest: description: Request body for creating a journey. type: object properties: name: type: string minLength: 1 nodes: minItems: 1 type: array items: $ref: '#/components/schemas/JourneyNode' enabled: type: boolean state: allOf: - $ref: '#/components/schemas/JourneyState' required: - name - nodes CancelJourneyRequest: description: >- Request body for `POST /journeys/cancel`. Provide EXACTLY ONE of `cancelation_token` (cancels every run associated with the token) or `run_id` (cancels a single tenant-scoped run). oneOf: - type: object title: By cancelation token properties: cancelation_token: type: string minLength: 1 required: - cancelation_token additionalProperties: false - type: object title: By run id properties: run_id: type: string minLength: 1 required: - run_id additionalProperties: false CancelJourneyResponse: description: >- `202 Accepted` body for `POST /journeys/cancel`, returning the submitted identifier. When called with `cancelation_token`, returns `{ cancelation_token }`; when called with `run_id`, returns `{ run_id, status }`. oneOf: - type: object title: Token branch properties: cancelation_token: type: string required: - cancelation_token - type: object title: Run id branch properties: run_id: type: string status: type: string description: >- The run's resulting status. `CANCELED` when the run was active and has been canceled; `PROCESSED` or `ERROR` when the run had already finished and was left unchanged; `CANCELED` for an already-canceled run. required: - run_id - status JourneyConditionAtom: title: Single condition description: >- A single condition expressed as a positional tuple of strings. - Binary form (3 elements): `[path, operator, value]` where `operator` is one of `is equal`, `is not equal`, `contains`, `does not contain`, `starts with`, `ends with`, `greater than`, `greater than or equal`, `less than`, `less than or equal`. Example: `["user.tier", "is equal", "gold"]`. - Unary form (2 elements): `[path, operator]` where `operator` is one of `exists`, `does not exist`. Example: `["user.email", "exists"]`. The first element is a non-empty dot-path. The second element is the operator (must come from one of the two operator sets above). For the binary form, the third element is the comparison value (string). Runtime validation of the operator value and arity is performed by the backend; SDKs surface this as a string list. type: array minItems: 2 maxItems: 3 items: type: string JourneyConditionGroup: title: Condition group type: object description: >- A leaf condition group. Exactly one of `AND` or `OR` must be present at runtime; each is a list of `JourneyConditionAtom` tuples. properties: AND: type: array minItems: 2 items: $ref: '#/components/schemas/JourneyConditionAtom' OR: type: array minItems: 2 items: $ref: '#/components/schemas/JourneyConditionAtom' JourneyConditionNestedGroup: title: Nested condition group type: object description: >- A nested condition group. Exactly one of `AND` or `OR` must be present at runtime; each is a list of `JourneyConditionGroup` items. properties: AND: type: array minItems: 2 items: $ref: '#/components/schemas/JourneyConditionGroup' OR: type: array minItems: 2 items: $ref: '#/components/schemas/JourneyConditionGroup' JourneyConditionsField: description: >- Condition spec for a journey node. Accepts a single condition atom, an AND/OR group, or an AND/OR nested group. Omit the `conditions` property entirely to express "no conditions". anyOf: - $ref: '#/components/schemas/JourneyConditionAtom' - $ref: '#/components/schemas/JourneyConditionGroup' - $ref: '#/components/schemas/JourneyConditionNestedGroup' JourneyMergeStrategy: description: Strategy for merging a fetch response into the journey run state. type: string enum: - overwrite - soft-merge - replace - none JourneyNode: description: >- A single node in a journey DAG. Discriminated by `type`, with a secondary discriminator on some variants (`trigger_type` for trigger, `mode` for delay, `method` for fetch, `scope` for throttle). oneOf: - $ref: '#/components/schemas/JourneyApiInvokeTriggerNode' - $ref: '#/components/schemas/JourneySegmentTriggerNode' - $ref: '#/components/schemas/JourneySendNode' - $ref: '#/components/schemas/JourneyDelayDurationNode' - $ref: '#/components/schemas/JourneyDelayUntilNode' - $ref: '#/components/schemas/JourneyFetchGetDeleteNode' - $ref: '#/components/schemas/JourneyFetchPostPutNode' - $ref: '#/components/schemas/JourneyAINode' - $ref: '#/components/schemas/JourneyThrottleStaticNode' - $ref: '#/components/schemas/JourneyThrottleDynamicNode' - $ref: '#/components/schemas/JourneyBatchNode' - $ref: '#/components/schemas/JourneyAddToDigestNode' - $ref: '#/components/schemas/JourneyExitNode' - type: object title: JourneyBranchNode description: >- Branch node. Routes to the first entry in `paths[]` whose `conditions` match, else falls through to `default.nodes`. properties: id: type: string minLength: 1 type: type: string enum: - branch paths: type: array minItems: 1 items: type: object properties: label: type: string minLength: 1 conditions: $ref: '#/components/schemas/JourneyConditionsField' nodes: type: array items: $ref: '#/components/schemas/JourneyNode' required: - conditions - nodes default: type: object properties: label: type: string minLength: 1 nodes: type: array items: $ref: '#/components/schemas/JourneyNode' required: - nodes required: - type - paths - default JourneyApiInvokeTriggerNode: title: API Invoke Trigger description: >- Trigger fired when the journey is invoked via the API. The optional `schema` field is a JSON Schema that validates the invocation payload. type: object properties: id: type: string minLength: 1 type: type: string enum: - trigger trigger_type: type: string enum: - api-invoke schema: type: object additionalProperties: true description: A JSONSchema object (Draft-07-compatible). Validated at runtime by Ajv. conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - trigger_type JourneySegmentTriggerNode: title: Segment Trigger description: Trigger fired by a segment event (`identify`, `group`, or `track`). type: object properties: id: type: string minLength: 1 type: type: string enum: - trigger trigger_type: type: string enum: - segment request_type: type: string enum: - identify - group - track event_id: type: string minLength: 1 conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - trigger_type - request_type JourneySendNode: title: Send description: >- Send to the recipient. A send node sources its content from EXACTLY ONE of `message.template` (a single notification template) or `experiment` (an A/B split across weighted template variants) — supplying both, or neither, is rejected. Optionally override the recipient address, delay the send, or attach `data`. type: object properties: id: type: string minLength: 1 type: type: string enum: - send message: type: object properties: template: type: string minLength: 1 to: type: object properties: email_override: type: string minLength: 1 phone_number_override: type: string minLength: 1 user_id_override: type: string minLength: 1 delay: type: object properties: until: type: string minLength: 1 timezone: type: string minLength: 1 required: - until data: type: object additionalProperties: true experiment: $ref: '#/components/schemas/JourneyExperiment' conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - message JourneyExperiment: title: Experiment description: >- A/B experiment config for a send node. The recipient is deterministically bucketed by `bucketingKey` and routed to one of the `variants` in proportion to its `weight`. Present on a send node INSTEAD OF `message.template`. type: object properties: id: type: string description: >- Unique experiment id (prefixed `exp_`). Omit to have one generated automatically; when supplied it must be a valid `exp_` id. minLength: 1 name: type: string description: Optional display name for the experiment. bucketingKey: type: string description: >- The value used to deterministically assign a recipient to a variant. Must be non-empty with no leading or trailing whitespace. minLength: 1 variants: type: array description: Between 2 and 10 weighted template variants. minItems: 2 maxItems: 10 items: $ref: '#/components/schemas/JourneyExperimentVariant' required: - bucketingKey - variants JourneyExperimentVariant: title: Experiment Variant description: >- A single weighted variant of an experiment. Variant ids must be unique within the experiment and the sum of all variant weights must be greater than 0. Weights are relative (no sum-to-100 requirement) — routing normalizes them proportionally. type: object properties: id: type: string minLength: 1 name: type: string description: Optional display name for the variant. weight: type: number description: Relative routing weight. Must be non-negative. minimum: 0 templateId: type: string description: The notification template sent for this variant. minLength: 1 required: - id - weight - templateId JourneyDelayDurationNode: title: Delay for Duration description: Pause the journey run for a fixed `duration`. type: object properties: id: type: string minLength: 1 type: type: string enum: - delay mode: type: string enum: - duration duration: type: string minLength: 1 conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - mode - duration JourneyDelayUntilNode: title: Delay Until description: Pause the journey run `until` a specific time. type: object properties: id: type: string minLength: 1 type: type: string enum: - delay mode: type: string enum: - until until: type: string minLength: 1 conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - mode - until JourneyFetchGetDeleteNode: title: Fetch (GET/DELETE) description: >- Issue an HTTP GET or DELETE request and merge the response into the journey state per `merge_strategy`. type: object properties: id: type: string minLength: 1 type: type: string enum: - fetch method: type: string enum: - get - delete url: type: string minLength: 1 merge_strategy: $ref: '#/components/schemas/JourneyMergeStrategy' headers: type: object additionalProperties: type: string query_params: type: object additionalProperties: type: string response_schema: type: object additionalProperties: true description: A JSONSchema object (Draft-07-compatible). Validated at runtime by Ajv. conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - method - url - merge_strategy JourneyFetchPostPutNode: title: Fetch (POST/PUT) description: >- Issue an HTTP POST or PUT request with a `body` and merge the response into the journey state per `merge_strategy`. type: object properties: id: type: string minLength: 1 type: type: string enum: - fetch method: type: string enum: - post - put url: type: string minLength: 1 merge_strategy: $ref: '#/components/schemas/JourneyMergeStrategy' headers: type: object additionalProperties: type: string query_params: type: object additionalProperties: type: string response_schema: type: object additionalProperties: true description: A JSONSchema object (Draft-07-compatible). Validated at runtime by Ajv. body: type: string conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - method - url - merge_strategy JourneyAINode: title: AI description: >- Invoke an AI step with `user_prompt` and optional `web_search`. Returns a structured response conforming to `output_schema`. type: object properties: id: type: string minLength: 1 type: type: string enum: - ai model: type: string minLength: 1 user_prompt: type: string web_search: type: boolean output_schema: type: object additionalProperties: true description: A JSONSchema object (Draft-07-compatible). Validated at runtime by Ajv. conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - output_schema JourneyThrottleStaticNode: title: Throttle (Static) description: >- Throttle the journey by a static `scope` (`user` or `global`), allowing at most `max_allowed` invocations per `period`. type: object properties: id: type: string minLength: 1 type: type: string enum: - throttle scope: type: string enum: - user - global max_allowed: type: integer minimum: 1 period: type: string minLength: 1 conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - scope - max_allowed - period JourneyThrottleDynamicNode: title: Throttle (Dynamic) description: >- Throttle the journey by a dynamic `throttle_key`, allowing at most `max_allowed` invocations per `period`. type: object properties: id: type: string minLength: 1 type: type: string enum: - throttle scope: type: string enum: - dynamic max_allowed: type: integer minimum: 1 period: type: string minLength: 1 throttle_key: type: string minLength: 1 conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - scope - max_allowed - period - throttle_key JourneyBatchNode: title: Batch description: >- Collect events arriving at the node into a single batch and fire one downstream step with the aggregated payload. The first event into a batch owns the run; later contributing events terminate at the batch step. The batch releases when any of `max_items` is reached, a quiet window of `wait_period` elapses, or the `max_wait_period` ceiling hits. type: object properties: id: type: string minLength: 1 type: type: string enum: - batch scope: type: string enum: - user wait_period: type: string minLength: 1 description: >- ISO 8601 duration. Quiet window that releases the batch when it elapses with no new contributing events. Must be less than `max_wait_period`. max_wait_period: type: string minLength: 1 description: >- ISO 8601 duration. Hard ceiling from the first event into the batch; releases the batch unconditionally when it elapses. max_items: type: integer default: 100 minimum: 1 maximum: 1000 description: Releases the batch once this many events have been collected. retain: type: object description: How to select which collected events to retain in the aggregated payload when the batch releases. properties: type: type: string enum: - first - last - highest - lowest count: type: integer minimum: 0 maximum: 25 sort_key: type: string minLength: 1 description: >- Dot-path into the event payload (e.g. `data.priority`). Required when `type` is `highest` or `lowest`. required: - type - count category_key: type: string minLength: 1 maxLength: 256 description: >- Optional partition key. Events with the same `category_key` are batched together; events with different values are batched separately. conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - scope - wait_period - max_wait_period - retain JourneyAddToDigestNode: title: Add to Digest description: >- Add the current event to a digest keyed by the given subscription topic. The digest accumulates events and releases them on the schedule configured for the topic. type: object properties: id: type: string minLength: 1 type: type: string enum: - add-to-digest subscription_topic_id: type: string minLength: 1 description: The subscription topic that owns the digest the event is added to. conditions: $ref: '#/components/schemas/JourneyConditionsField' required: - type - subscription_topic_id JourneyExitNode: title: Exit description: Terminate the journey run. type: object properties: id: type: string minLength: 1 type: type: string enum: - exit required: - type JourneyTemplateCreateRequest: description: Request body for creating a notification template scoped to a journey. type: object properties: state: type: string channel: type: string minLength: 1 notification: type: object properties: name: type: string tags: type: array items: type: string brand: nullable: true type: object properties: id: type: string required: - id subscription: nullable: true type: object properties: topic_id: type: string required: - topic_id content: type: object properties: elements: type: array items: $ref: '#/components/schemas/ElementalNode' scope: type: string enum: - default - strict version: type: string enum: - '2022-01-01' required: - elements - version required: - name - tags - brand - subscription - content providerKey: type: string minLength: 1 required: - channel - notification JourneyTemplateGetResponse: description: A journey-scoped notification template. type: object properties: name: type: string tags: type: array items: type: string brand: nullable: true type: object properties: id: type: string required: - id subscription: nullable: true type: object properties: topic_id: type: string required: - topic_id content: type: object properties: elements: type: array items: $ref: '#/components/schemas/ElementalNode' scope: type: string enum: - default - strict version: type: string enum: - '2022-01-01' required: - elements - version id: type: string state: default: DRAFT type: string enum: - DRAFT - PUBLISHED created: type: integer format: int64 creator: type: string updated: type: integer format: int64 updater: type: string required: - name - tags - brand - subscription - content - id - state - created - creator JourneyTemplateReplaceRequest: description: Request body for replacing a journey-scoped notification template draft. type: object properties: notification: type: object properties: name: type: string tags: type: array items: type: string brand: nullable: true type: object properties: id: type: string required: - id subscription: nullable: true type: object properties: topic_id: type: string required: - topic_id content: type: object properties: elements: type: array items: $ref: '#/components/schemas/ElementalNode' scope: type: string enum: - default - strict version: type: string enum: - '2022-01-01' required: - elements - version required: - name - tags - brand - subscription - content state: type: string required: - notification JourneyPublishRequest: description: >- Request body for publishing a journey. Pass `version` to roll back to a prior version; omit to publish the current draft. type: object properties: version: type: string pattern: ^v\d+$ JourneyResponse: description: A journey, with its current draft or published nodes and metadata. type: object properties: id: type: string name: type: string state: $ref: '#/components/schemas/JourneyState' enabled: type: boolean nodes: type: array items: $ref: '#/components/schemas/JourneyNode' created: nullable: true type: integer format: int64 creator: nullable: true type: string updated: nullable: true type: integer format: int64 updater: nullable: true type: string published: nullable: true type: integer format: int64 required: - id - name - state - enabled - nodes - created - creator - updated - updater - published JourneyState: description: Lifecycle state of a journey. type: string enum: - DRAFT - PUBLISHED JourneyVersionItem: description: A published version of a journey. type: object properties: version: type: string name: type: string created: nullable: true type: integer format: int64 creator: nullable: true type: string published: nullable: true type: integer format: int64 required: - version - name - created - creator - published JourneyVersionsListResponse: description: Paged list of published journey versions, most recent first. type: object properties: results: type: array items: $ref: '#/components/schemas/JourneyVersionItem' paging: $ref: '#/components/schemas/Paging' required: - results - paging JourneyTemplateSummary: description: Summary fields of a journey-scoped notification template returned in list responses. type: object properties: id: type: string name: type: string tags: type: array items: type: string state: type: string created: type: integer format: int64 creator: type: string updated: type: integer format: int64 updater: type: string required: - id - name - tags - state - created - creator JourneyTemplatePublishRequest: description: >- Request body for publishing a journey-scoped notification template. Pass `version` to roll back to a prior version; omit to publish the current draft. type: object properties: version: type: string pattern: ^v\d+$ JourneyTemplateListResponse: description: Paged list of journey-scoped notification templates. type: object properties: results: type: array items: $ref: '#/components/schemas/JourneyTemplateSummary' paging: $ref: '#/components/schemas/Paging' required: - results - paging Brand: title: Brand type: object properties: id: type: string name: type: string published: type: integer format: int64 nullable: true created: type: integer format: int64 updated: type: integer format: int64 settings: $ref: '#/components/schemas/BrandSettings' nullable: true snippets: $ref: '#/components/schemas/BrandSnippets' nullable: true version: type: string nullable: true required: - id - name - created - updated BrandParameters: title: BrandParameters type: object properties: id: type: string nullable: true name: type: string settings: $ref: '#/components/schemas/BrandSettings' snippets: $ref: '#/components/schemas/BrandSnippets' nullable: true required: - name - settings BrandSettings: title: BrandSettings type: object properties: colors: $ref: '#/components/schemas/BrandColors' nullable: true email: $ref: '#/components/schemas/BrandSettingsEmail' nullable: true inapp: $ref: '#/components/schemas/BrandSettingsInApp' nullable: true BrandColors: title: BrandColors type: object properties: primary: type: string secondary: type: string additionalProperties: type: string BrandSnippets: title: BrandSnippets type: object properties: items: type: array items: $ref: '#/components/schemas/BrandSnippet' nullable: true BrandSnippet: title: BrandSnippet type: object properties: name: type: string value: type: string required: - name - value BrandsResponse: title: BrandsResponse type: object properties: paging: $ref: '#/components/schemas/Paging' results: type: array items: $ref: '#/components/schemas/Brand' required: - paging - results BrandSettingsEmail: title: BrandSettingsEmail type: object properties: templateOverride: $ref: '#/components/schemas/BrandTemplateOverride' nullable: true head: $ref: '#/components/schemas/EmailHead' nullable: true footer: $ref: '#/components/schemas/EmailFooter' nullable: true header: $ref: '#/components/schemas/EmailHeader' nullable: true EmailHead: title: EmailHead type: object properties: inheritDefault: type: boolean content: type: string nullable: true required: - inheritDefault EmailFooter: title: EmailFooter type: object properties: content: type: string nullable: true inheritDefault: type: boolean nullable: true EmailHeader: title: EmailHeader type: object properties: inheritDefault: type: boolean nullable: true barColor: type: string nullable: true logo: $ref: '#/components/schemas/Logo' required: - logo Logo: title: Logo type: object properties: href: type: string nullable: true image: type: string nullable: true BrandTemplate: title: BrandTemplate type: object properties: backgroundColor: type: string nullable: true blocksBackgroundColor: type: string nullable: true enabled: type: boolean footer: type: string nullable: true head: type: string nullable: true header: type: string nullable: true width: type: string nullable: true required: - enabled BrandTemplateOverride: title: BrandTemplateOverride type: object properties: mjml: $ref: '#/components/schemas/BrandTemplate' footerBackgroundColor: type: string nullable: true footerFullWidth: type: boolean nullable: true required: - mjml allOf: - $ref: '#/components/schemas/BrandTemplate' BrandSettingsSocialPresence: title: BrandSettingsSocialPresence type: object properties: inheritDefault: type: boolean nullable: true facebook: $ref: '#/components/schemas/BaseSocialPresence' nullable: true instagram: $ref: '#/components/schemas/BaseSocialPresence' nullable: true linkedin: $ref: '#/components/schemas/BaseSocialPresence' nullable: true medium: $ref: '#/components/schemas/BaseSocialPresence' nullable: true twitter: $ref: '#/components/schemas/BaseSocialPresence' nullable: true BaseSocialPresence: title: BaseSocialPresence type: object properties: url: type: string required: - url BrandSettingsInApp: title: BrandSettingsInApp type: object properties: borderRadius: type: string nullable: true disableMessageIcon: type: boolean nullable: true fontFamily: type: string nullable: true placement: $ref: '#/components/schemas/InAppPlacement' nullable: true widgetBackground: $ref: '#/components/schemas/WidgetBackground' colors: $ref: '#/components/schemas/BrandColors' icons: $ref: '#/components/schemas/Icons' required: - widgetBackground - colors - icons InAppPlacement: title: InAppPlacement type: string enum: - top - bottom - left - right WidgetBackground: title: WidgetBackground type: object properties: topColor: type: string nullable: true bottomColor: type: string nullable: true Icons: title: Icons type: object properties: bell: type: string nullable: true message: type: string nullable: true Provider: title: Provider type: object description: A configured provider in the workspace. properties: id: type: string description: A unique identifier for the provider configuration. title: type: string description: Display title. Defaults to "Default Configuration" when not explicitly set. provider: type: string description: The provider key (e.g. "sendgrid", "twilio", "slack"). alias: type: string description: Optional alias for this configuration. settings: type: object description: Provider-specific settings (snake_case keys on the wire). additionalProperties: true created: type: integer description: Unix timestamp (ms) of when the provider was created. updated: type: integer nullable: true description: Unix timestamp (ms) of when the provider was last updated. required: - id - title - provider - settings - created ProvidersCreateRequest: title: ProvidersCreateRequest type: object description: Request body for creating a new provider configuration. properties: provider: type: string maxLength: 128 description: >- The provider key identifying the type (e.g. "sendgrid", "twilio"). Must be a known Courier provider — see the catalog endpoint for valid keys. title: type: string description: Optional display title. Omit to use "Default Configuration". alias: type: string description: Optional alias for this configuration. settings: type: object description: >- Provider-specific settings (snake_case keys). Defaults to an empty object when omitted. Use the catalog endpoint to discover required fields for a given provider — omitting a required field returns a 400 validation error. additionalProperties: true required: - provider ProvidersUpdateRequest: title: ProvidersUpdateRequest type: object description: >- Request body for replacing an existing provider configuration. The `provider` key is required because it determines which provider-specific settings schema is validated against. Changing the provider type for an existing configuration is not supported. All other fields are optional — omitted fields are cleared from the stored configuration (this is a full replacement, not a partial merge). properties: provider: type: string maxLength: 128 description: >- The provider key identifying the type. Required on every request because it selects the provider-specific settings schema for validation. title: type: string description: Updated display title. alias: type: string description: Updated alias. Omit to clear. settings: type: object description: >- Provider-specific settings (snake_case keys). Replaces the full settings object — omitted settings fields are removed. Use the catalog endpoint to check required fields. additionalProperties: true required: - provider ProvidersListResponse: title: ProvidersListResponse type: object description: Paginated list of provider configurations. properties: paging: $ref: '#/components/schemas/Paging' results: type: array items: $ref: '#/components/schemas/Provider' required: - paging - results ProviderSchemaField: title: ProviderSchemaField type: object description: Describes a single configuration field in the provider catalog. properties: type: type: string description: The field's data type (e.g. "string", "boolean", "enum"). required: type: boolean description: Whether this field is required when configuring the provider. values: type: array items: type: string description: Allowed values when `type` is "enum". required: - type - required ProvidersCatalogEntry: title: ProvidersCatalogEntry type: object description: >- A provider type from the catalog. Contains the key, display name, description, and a `settings` object describing configuration schema fields. properties: provider: type: string description: The provider key (e.g. "sendgrid", "twilio"). name: type: string description: Human-readable display name. description: type: string description: Short description of the provider. channel: type: string description: Courier taxonomy channel (e.g. email, push, sms, direct_message, inbox, webhook). settings: type: object description: >- Map of setting field names (snake_case) to their schema descriptors. Each descriptor has `type` and `required`. Empty when the provider has no configurable schema. additionalProperties: $ref: '#/components/schemas/ProviderSchemaField' required: - provider - name - description - channel - settings ProvidersCatalogResponse: title: ProvidersCatalogResponse type: object description: Paginated list of available provider types with their configuration schemas. properties: paging: $ref: '#/components/schemas/Paging' results: type: array items: $ref: '#/components/schemas/ProvidersCatalogEntry' required: - paging - results BaseError: title: BaseError type: object properties: message: type: string description: A message describing the error that occurred. required: - message BadRequest: title: BadRequest type: object properties: type: type: string enum: - invalid_request_error required: - type allOf: - $ref: '#/components/schemas/BaseError' PaymentRequired: title: PaymentRequired type: object properties: type: type: string enum: - authorization_error required: - type allOf: - $ref: '#/components/schemas/BaseError' AlreadyExists: title: AlreadyExists type: object properties: type: type: string enum: - invalid_request_error required: - type allOf: - $ref: '#/components/schemas/BaseError' Conflict: title: Conflict type: object properties: type: type: string enum: - invalid_request_error required: - type allOf: - $ref: '#/components/schemas/BaseError' NotFound: title: NotFound type: object properties: type: type: string enum: - invalid_request_error required: - type allOf: - $ref: '#/components/schemas/BaseError' UnprocessableEntity: title: UnprocessableEntity type: object properties: type: type: string enum: - invalid_request_error required: - type allOf: - $ref: '#/components/schemas/BaseError' MessageNotFound: title: MessageNotFound type: object properties: type: type: string enum: - invalid_request_error required: - type allOf: - $ref: '#/components/schemas/BaseError' TooManyRequests: title: TooManyRequests type: object properties: type: type: string enum: - rate_limit_error required: - type allOf: - $ref: '#/components/schemas/BaseError' InboundTrackEvent: title: InboundTrackEvent type: object properties: event: type: string description: >- A descriptive name of the event. This name will appear as a trigger in the Courier Automation Trigger node. example: New Order Placed messageId: type: string description: >- A required unique identifier that will be used to de-duplicate requests. If not unique, will respond with 409 Conflict status example: 4c62c457-b329-4bea-9bfc-17bba86c393f properties: type: object additionalProperties: true type: type: string enum: - track userId: type: string nullable: true description: The user id associated with the track required: - event - messageId - properties - type TrackAcceptedResponse: title: TrackAcceptedResponse type: object properties: messageId: type: string description: A successful call returns a `202` status code along with a `requestId` in the response body. example: 1-65f240a0-47a6a120c8374de9bcf9f22c required: - messageId SubscriptionList: title: SubscriptionList type: object properties: id: type: string name: type: string created: type: string nullable: true updated: type: string nullable: true required: - id - name ListPutParams: title: ListPutParams type: object properties: name: type: string preferences: $ref: '#/components/schemas/RecipientPreferences' nullable: true required: - name ListGetAllResponse: title: ListGetAllResponse type: object properties: paging: $ref: '#/components/schemas/Paging' items: type: array items: $ref: '#/components/schemas/SubscriptionList' required: - paging - items ListSubscriptionRecipient: title: ListSubscriptionRecipient type: object properties: recipientId: type: string created: type: string nullable: true preferences: $ref: '#/components/schemas/RecipientPreferences' nullable: true required: - recipientId ListGetSubscriptionsResponse: title: ListGetSubscriptionsResponse type: object properties: paging: $ref: '#/components/schemas/Paging' items: type: array items: $ref: '#/components/schemas/ListSubscriptionRecipient' required: - paging - items PutSubscriptionsRecipient: title: PutSubscriptionsRecipient type: object properties: recipientId: type: string preferences: $ref: '#/components/schemas/RecipientPreferences' nullable: true required: - recipientId RecipientPreferences: title: RecipientPreferences type: object properties: categories: $ref: '#/components/schemas/NotificationPreferences' nullable: true notifications: $ref: '#/components/schemas/NotificationPreferences' nullable: true NotificationPreferences: title: NotificationPreferences type: object additionalProperties: $ref: '#/components/schemas/NotificationPreferenceDetails' NotificationPreferenceDetails: title: NotificationPreferenceDetails type: object properties: status: $ref: '#/components/schemas/PreferenceStatus' rules: type: array items: $ref: '#/components/schemas/Rule' nullable: true channel_preferences: type: array items: $ref: '#/components/schemas/ChannelPreference' nullable: true required: - status MessageStatus: title: MessageStatus type: string enum: - CANCELED - CLICKED - DELAYED - DELIVERED - DIGESTED - ENQUEUED - FILTERED - OPENED - ROUTED - SENT - SIMULATED - THROTTLED - UNDELIVERABLE - UNMAPPED - UNROUTABLE MessageDetails: title: MessageDetails type: object properties: id: type: string description: A unique identifier associated with the message you wish to retrieve (results from a send). status: $ref: '#/components/schemas/MessageStatus' description: The current status of the message. enqueued: type: integer format: int64 description: >- A UTC timestamp at which Courier received the message request. Stored as a millisecond representation of the Unix epoch. sent: type: integer format: int64 description: >- A UTC timestamp at which Courier passed the message to the Integration provider. Stored as a millisecond representation of the Unix epoch. delivered: type: integer format: int64 description: >- A UTC timestamp at which the Integration provider delivered the message. Stored as a millisecond representation of the Unix epoch. opened: type: integer format: int64 description: >- A UTC timestamp at which the recipient opened a message for the first time. Stored as a millisecond representation of the Unix epoch. clicked: type: integer format: int64 description: >- A UTC timestamp at which the recipient clicked on a tracked link for the first time. Stored as a millisecond representation of the Unix epoch. recipient: type: string description: A unique identifier associated with the recipient of the delivered message. event: type: string description: A unique identifier associated with the event of the delivered message. notification: type: string description: A unique identifier associated with the notification of the delivered message. error: type: string nullable: true description: A message describing the error that occurred. reason: $ref: '#/components/schemas/Reason' nullable: true description: The reason for the current status of the message. required: - id - status - enqueued - recipient - event - notification MessageDetailsExtended: title: MessageDetailsExtended type: object properties: providers: type: array items: type: object additionalProperties: true nullable: true allOf: - $ref: '#/components/schemas/MessageDetails' Reason: title: Reason type: string enum: - BOUNCED - FAILED - FILTERED - NO_CHANNELS - NO_PROVIDERS - OPT_IN_REQUIRED - PROVIDER_ERROR - UNPUBLISHED - UNSUBSCRIBED ListMessagesResponse: title: ListMessagesResponse type: object properties: paging: $ref: '#/components/schemas/Paging' description: Paging information for the result set. results: type: array items: $ref: '#/components/schemas/MessageDetails' description: An array of messages with their details. required: - paging - results MessageHistoryResponse: title: MessageHistoryResponse type: object properties: results: type: array items: type: object additionalProperties: true required: - results RenderOutputResponse: title: RenderOutputResponse type: object properties: results: type: array items: $ref: '#/components/schemas/RenderOutput' description: An array of render output of a previously sent message. required: - results RenderedMessageBlock: title: RenderedMessageBlock type: object properties: type: type: string description: The block type of the rendered message block. text: type: string description: The block text of the rendered message block. required: - type - text RenderedMessageContent: title: RenderedMessageContent type: object properties: html: type: string description: The html content of the rendered message. title: type: string description: The title of the rendered message. body: type: string description: The body of the rendered message. subject: type: string description: The subject of the rendered message. text: type: string description: The text of the rendered message. blocks: type: array items: $ref: '#/components/schemas/RenderedMessageBlock' description: The blocks of the rendered message. required: - html - title - body - subject - text - blocks RenderOutput: title: RenderOutput type: object properties: channel: type: string description: The channel used for rendering the message. channel_id: type: string description: The ID of channel used for rendering the message. content: $ref: '#/components/schemas/RenderedMessageContent' description: Content details of the rendered message. required: - channel - channel_id - content NotificationListResponse: title: NotificationListResponse type: object properties: paging: $ref: '#/components/schemas/Paging' results: type: array description: Notification templates in this workspace. items: oneOf: - $ref: '#/components/schemas/Notification' - $ref: '#/components/schemas/NotificationTemplateSummary' required: - paging - results NotificationGetContentResponse: title: NotificationGetContentResponse type: object properties: blocks: type: array items: $ref: '#/components/schemas/NotificationBlock' nullable: true channels: type: array items: $ref: '#/components/schemas/NotificationChannel' nullable: true checksum: type: string nullable: true Notification: title: Notification type: object properties: created_at: type: integer format: int64 updated_at: type: integer format: int64 id: type: string routing: $ref: '#/components/schemas/MessageRouting' tags: $ref: '#/components/schemas/NotificationTag' nullable: true title: type: string nullable: true topic_id: type: string note: type: string event_ids: type: array items: type: string description: Array of event IDs associated with this notification required: - created_at - updated_at - id - routing - topic_id - event_ids NotificationTag: title: NotificationTag type: object properties: data: type: array items: $ref: '#/components/schemas/NotificationTagData' required: - data NotificationTagData: title: NotificationTagData type: object properties: id: type: string name: type: string required: - id - name NotificationBlock: title: NotificationBlock type: object properties: alias: type: string nullable: true context: type: string nullable: true id: type: string type: $ref: '#/components/schemas/BlockType' content: $ref: '#/components/schemas/NotificationContent' nullable: true locales: type: object additionalProperties: $ref: '#/components/schemas/NotificationContent' nullable: true checksum: type: string nullable: true required: - id - type NotificationContent: title: NotificationContent oneOf: - type: string - $ref: '#/components/schemas/NotificationContentHierarchy' NotificationContentHierarchy: title: NotificationContentHierarchy type: object properties: parent: type: string nullable: true children: type: string nullable: true BlockType: title: BlockType type: string enum: - action - divider - image - jsonnet - list - markdown - quote - template - text NotificationChannel: title: NotificationChannel type: object properties: id: type: string type: type: string nullable: true content: $ref: '#/components/schemas/NotificationChannelContent' nullable: true locales: type: object additionalProperties: $ref: '#/components/schemas/NotificationChannelContent' nullable: true checksum: type: string nullable: true required: - id NotificationChannelContent: title: NotificationChannelContent type: object properties: subject: type: string nullable: true title: type: string nullable: true NotificationTemplatePayload: title: NotificationTemplatePayload type: object description: >- Core template fields used in POST and PUT request bodies (nested under a `notification` key) and returned at the top level in responses. properties: name: type: string description: Display name for the template. tags: type: array items: type: string description: Tags for categorization. Send empty array for none. brand: nullable: true type: object description: Brand reference, or null for no brand. properties: id: type: string required: - id subscription: nullable: true type: object description: Subscription topic reference, or null for none. properties: topic_id: type: string required: - topic_id routing: nullable: true type: object description: Routing strategy reference, or null for none. properties: strategy_id: type: string required: - strategy_id content: $ref: '#/components/schemas/ElementalContent' description: Elemental content definition. required: - name - tags - brand - subscription - routing - content NotificationTemplateCreateRequest: title: NotificationTemplateCreateRequest type: object description: Request body for creating a notification template. properties: notification: $ref: '#/components/schemas/NotificationTemplatePayload' state: type: string description: >- Template state after creation. Case-insensitive input, normalized to uppercase in the response. Defaults to "DRAFT". enum: - DRAFT - PUBLISHED default: DRAFT required: - notification NotificationTemplateUpdateRequest: title: NotificationTemplateUpdateRequest type: object description: >- Request body for replacing a notification template. Same shape as create. All fields required (PUT = full replacement). properties: notification: $ref: '#/components/schemas/NotificationTemplatePayload' state: type: string description: >- Template state after update. Case-insensitive input, normalized to uppercase in the response. Defaults to "DRAFT". enum: - DRAFT - PUBLISHED default: DRAFT required: - notification NotificationTemplateMutationResponse: title: NotificationTemplateMutationResponse type: object deprecated: true description: >- Deprecated — mutation endpoints now return NotificationTemplateResponse. Retained for backward compatibility with generated SDKs. properties: notification: type: object properties: id: type: string description: The ID of the created or updated template. required: - id state: type: string description: The template state after the operation. Always uppercase. enum: - DRAFT - PUBLISHED required: - notification - state NotificationTemplateResponse: title: NotificationTemplateResponse description: >- Response for GET /notifications/{id}, POST /notifications, and PUT /notifications/{id}. Returns all template fields at the top level. allOf: - $ref: '#/components/schemas/NotificationTemplatePayload' - type: object properties: id: type: string description: The template ID. state: type: string description: The template state. Always uppercase. enum: - DRAFT - PUBLISHED created: type: integer format: int64 description: Epoch milliseconds when the template was created. creator: type: string description: User ID of the creator. updated: type: integer format: int64 description: Epoch milliseconds of last update. updater: type: string description: User ID of the last updater. required: - id - state - created - creator NotificationTemplateSummary: title: NotificationTemplateSummary type: object description: V2 (CDS) template summary returned in list responses. properties: id: type: string name: type: string tags: type: array items: type: string state: type: string enum: - DRAFT - PUBLISHED created: type: integer format: int64 description: Epoch milliseconds when the template was created. creator: type: string description: User ID of the creator. updated: type: integer format: int64 description: Epoch milliseconds of last update. updater: type: string description: User ID of the last updater. subscription_topic_id: type: string description: >- The linked subscription (preference) topic of the published version. Omitted when no topic is linked or the template has never been published. topic_id: type: string description: >- Alias of subscription_topic_id, provided under the same name V1 list items use for the linked topic. Always carries the same value as subscription_topic_id. required: - id - name - tags - state - created - creator VersionNode: title: VersionNode type: object description: A version entry for a notification template. properties: version: type: string description: >- Version identifier. One of "draft", "published:vNNN" (current published version), or "vNNN" (historical version). created: type: integer format: int64 description: Epoch milliseconds when this version was created. creator: type: string description: User ID of the version creator. has_changes: type: boolean description: Whether the draft has unpublished changes. Only present on the draft version. required: - version - created - creator NotificationTemplateVersionListResponse: title: NotificationTemplateVersionListResponse type: object properties: versions: type: array items: $ref: '#/components/schemas/VersionNode' paging: $ref: '#/components/schemas/Paging' required: - versions - paging NotificationTemplatePublishRequest: title: NotificationTemplatePublishRequest type: object description: >- Optional request body for publishing a notification template. Omit or send an empty object to publish the current draft. properties: version: type: string pattern: ^v\d+$ description: Historical version to publish (e.g. "v001"). Omit to publish the current draft. BaseCheck: title: BaseCheck type: object properties: id: type: string status: $ref: '#/components/schemas/CheckStatus' type: type: string enum: - custom required: - id - status - type Check: title: Check type: object properties: updated: type: integer format: int64 required: - updated allOf: - $ref: '#/components/schemas/BaseCheck' CheckStatus: title: CheckStatus type: string enum: - RESOLVED - FAILED - PENDING SubmissionChecksGetResponse: title: SubmissionChecksGetResponse type: object properties: checks: type: array items: $ref: '#/components/schemas/Check' required: - checks SubmissionChecksReplaceResponse: title: SubmissionChecksReplaceResponse type: object properties: checks: type: array items: $ref: '#/components/schemas/Check' required: - checks NotificationTemplateState: title: NotificationTemplateState type: string description: Template state. Defaults to `DRAFT`. enum: - DRAFT - PUBLISHED default: DRAFT NotificationContentGetResponse: title: NotificationContentGetResponse type: object description: Elemental content response for V2 templates. Contains versioned elements with content checksums. properties: version: type: string description: Content version identifier. example: '2022-01-01' elements: type: array items: $ref: '#/components/schemas/ElementWithChecksums' required: - version - elements ElementWithChecksums: title: ElementWithChecksums type: object description: An element with its content checksum and optional nested elements and locale checksums. properties: id: type: string checksum: type: string description: MD5 hash of translatable content. type: type: string description: Element type (text, meta, action, etc.). elements: type: array items: $ref: '#/components/schemas/ElementWithChecksums' description: Nested child elements (for group-type elements). locales: type: object additionalProperties: type: object properties: checksum: type: string required: - checksum description: Locale-specific content with checksums. required: - checksum - type additionalProperties: true NotificationContentPutRequest: title: NotificationContentPutRequest type: object description: Request body for replacing the elemental content of a notification template. properties: content: type: object description: Elemental content payload. The server defaults `version` when omitted. properties: version: type: string description: Content version identifier (e.g., `2022-01-01`). Optional; server defaults when omitted. elements: type: array items: $ref: '#/components/schemas/ElementalNode' required: - elements state: $ref: '#/components/schemas/NotificationTemplateState' required: - content NotificationContentMutationResponse: title: NotificationContentMutationResponse type: object description: >- Shared mutation response for `PUT` content, `PUT` element, and `PUT` locale operations. Contains the template ID, content version, per-element checksums, and resulting state. properties: id: type: string description: Template ID. version: type: string description: Content version identifier. elements: type: array items: type: object properties: id: type: string checksum: type: string required: - id - checksum state: $ref: '#/components/schemas/NotificationTemplateState' required: - id - version - elements - state NotificationElementPutRequest: title: NotificationElementPutRequest type: object description: Request body for updating a single element. Additional type-specific fields are allowed. properties: type: type: string description: Element type (text, meta, action, image, etc.). channels: type: array items: type: string data: type: object additionalProperties: true if: type: string loop: type: string ref: type: string state: $ref: '#/components/schemas/NotificationTemplateState' required: - type additionalProperties: true NotificationLocalePutRequest: title: NotificationLocalePutRequest type: object description: >- Request body for setting locale-specific content overrides. Each element override must include the target element ID. properties: elements: type: array items: type: object properties: id: type: string description: Target element ID. required: - id additionalProperties: true description: Elements with locale-specific content overrides. state: $ref: '#/components/schemas/NotificationTemplateState' required: - elements Address: title: Address type: object properties: formatted: type: string street_address: type: string locality: type: string region: type: string postal_code: type: string country: type: string required: - formatted - street_address - locality - region - postal_code - country ProfileGetResponse: title: ProfileGetResponse type: object properties: profile: type: object additionalProperties: true preferences: $ref: '#/components/schemas/RecipientPreferences' nullable: true required: - profile MergeProfileResponse: title: MergeProfileResponse type: object properties: status: type: string enum: - SUCCESS required: - status ReplaceProfileResponse: title: ReplaceProfileResponse type: object properties: status: type: string enum: - SUCCESS required: - status ProfileUpdateRequest: title: ProfileUpdateRequest type: object properties: patch: type: array items: $ref: '#/components/schemas/UserProfilePatch' description: List of patch operations to apply to the profile. required: - patch UserProfilePatch: title: UserProfilePatch type: object properties: op: type: string description: The operation to perform. path: type: string description: The JSON path specifying the part of the profile to operate on. value: type: string description: The value for the operation. required: - op - path - value SubscribeToListsRequest: title: SubscribeToListsRequest type: object properties: lists: type: array items: $ref: '#/components/schemas/SubscribeToListsRequestItem' required: - lists SubscribeToListsRequestItem: title: SubscribeToListsRequestItem type: object properties: listId: type: string preferences: $ref: '#/components/schemas/RecipientPreferences' nullable: true required: - listId SubscribeToListsResponse: title: SubscribeToListsResponse type: object properties: status: type: string enum: - SUCCESS required: - status DeleteListSubscriptionResponse: title: DeleteListSubscriptionResponse type: object properties: status: type: string enum: - SUCCESS required: - status GetListSubscriptionsItem: title: GetListSubscriptionsItem type: object properties: id: type: string name: type: string description: List name created: type: string description: The date/time of when the list was created. Represented as a string in ISO format. updated: type: string description: The date/time of when the list was updated. Represented as a string in ISO format. preferences: $ref: '#/components/schemas/RecipientPreferences' nullable: true required: - id - name - created - updated GetListSubscriptionsResponse: title: GetListSubscriptionsResponse type: object properties: paging: $ref: '#/components/schemas/Paging' results: type: array items: $ref: '#/components/schemas/GetListSubscriptionsItem' description: An array of lists required: - paging - results Tenant: title: Tenant type: object properties: id: type: string description: Id of the tenant. name: type: string description: Name of the tenant. parent_tenant_id: type: string nullable: true description: Tenant's parent id (if any). default_preferences: $ref: '#/components/schemas/DefaultPreferences' nullable: true description: Defines the preferences used for the account when the user hasn't specified their own. properties: type: object additionalProperties: true nullable: true description: Arbitrary properties accessible to a template. user_profile: type: object additionalProperties: true nullable: true description: A user profile object merged with user profile on send. brand_id: type: string nullable: true description: Brand to be used for the account when one is not specified by the send call. required: - id - name DefaultPreferences: title: DefaultPreferences type: object properties: items: type: array items: $ref: '#/components/schemas/SubscriptionTopic' nullable: true SubscriptionTopicNew: title: SubscriptionTopicNew type: object properties: status: $ref: '#/components/schemas/SubscriptionTopicStatus' has_custom_routing: type: boolean nullable: true description: >- Override channel routing with custom preferences. This will override any template preferences that are set, but a user can still customize their preferences custom_routing: type: array items: $ref: '#/components/schemas/ChannelClassification' nullable: true description: The default channels to send to this tenant when has_custom_routing is enabled required: - status SubscriptionTopic: title: SubscriptionTopic type: object properties: id: type: string description: Topic ID required: - id allOf: - $ref: '#/components/schemas/SubscriptionTopicNew' SubscriptionTopicStatus: title: SubscriptionTopicStatus type: string enum: - OPTED_OUT - OPTED_IN - REQUIRED TenantListResponse: title: TenantListResponse type: object properties: cursor: type: string nullable: true description: A pointer to the next page of results. Defined only when has_more is set to true. has_more: type: boolean description: Set to true when there are more pages that can be retrieved. items: type: array items: $ref: '#/components/schemas/Tenant' description: An array of Tenants next_url: type: string nullable: true description: |- A url that may be used to generate fetch the next set of results. Defined only when has_more is set to true url: type: string description: A url that may be used to generate these results. type: type: string enum: - list description: Always set to "list". Represents the type of this object. required: - has_more - items - url - type ListUsersForTenantResponse: title: ListUsersForTenantResponse type: object properties: items: type: array items: $ref: '#/components/schemas/UserTenantAssociation' nullable: true has_more: type: boolean description: Set to true when there are more pages that can be retrieved. url: type: string description: A url that may be used to generate these results. next_url: type: string nullable: true description: |- A url that may be used to generate fetch the next set of results. Defined only when `has_more` is set to true cursor: type: string nullable: true description: |- A pointer to the next page of results. Defined only when `has_more` is set to true type: type: string enum: - list description: Always set to `list`. Represents the type of this object. required: - has_more - url - type UserTenantAssociation: title: UserTenantAssociation type: object properties: user_id: type: string nullable: true description: User ID for the association between tenant and user type: type: string enum: - user nullable: true tenant_id: type: string description: Tenant ID for the association between tenant and user profile: type: object additionalProperties: true nullable: true description: Additional metadata to be applied to a user profile when used in a tenant context required: - tenant_id GetTemplateByTenantResponse: title: GetTemplateByTenantResponse type: object properties: {} allOf: - $ref: '#/components/schemas/SingleTemplateTenantAssociation' ListTemplatesByTenantResponse: title: ListTemplatesByTenantResponse type: object properties: items: type: array items: $ref: '#/components/schemas/ListTemplateTenantAssociation' nullable: true has_more: type: boolean description: Set to true when there are more pages that can be retrieved. url: type: string description: A url that may be used to generate these results. next_url: type: string nullable: true description: |- A url that may be used to generate fetch the next set of results. Defined only when `has_more` is set to true cursor: type: string nullable: true description: |- A pointer to the next page of results. Defined only when `has_more` is set to true type: type: string enum: - list description: Always set to `list`. Represents the type of this object. required: - has_more - url - type BaseTemplateTenantAssociation: title: BaseTemplateTenantAssociation type: object properties: id: type: string description: The template's id created_at: type: string description: The timestamp at which the template was created updated_at: type: string description: The timestamp at which the template was last updated published_at: type: string description: The timestamp at which the template was published version: type: string description: The version of the template required: - id - created_at - updated_at - published_at - version SingleTemplateTenantAssociation: title: SingleTemplateTenantAssociation type: object properties: data: $ref: '#/components/schemas/TenantTemplateData' required: - data allOf: - $ref: '#/components/schemas/BaseTemplateTenantAssociation' ListTemplateTenantAssociation: title: ListTemplateTenantAssociation type: object properties: data: $ref: '#/components/schemas/TenantTemplateDataNoContent' required: - data allOf: - $ref: '#/components/schemas/BaseTemplateTenantAssociation' TenantTemplateData: title: TenantTemplateData type: object description: The template's data containing it's routing configs and Elemental content properties: routing: $ref: '#/components/schemas/MessageRouting' content: $ref: '#/components/schemas/ElementalContent' required: - routing - content TenantTemplateDataNoContent: title: TenantTemplateDataNoContent type: object description: The template's data containing it's routing configs properties: routing: $ref: '#/components/schemas/MessageRouting' required: - routing PutTenantTemplateRequest: title: PutTenantTemplateRequest type: object description: Request body for creating or updating a tenant notification template properties: published: type: boolean default: false description: >- Whether to publish the template immediately after saving. When true, the template becomes the active/published version. When false (default), the template is saved as a draft. template: $ref: '#/components/schemas/TenantTemplateInput' required: - template TenantTemplateInput: title: TenantTemplateInput type: object description: Template configuration for creating or updating a tenant notification template properties: channels: $ref: '#/components/schemas/MessageChannels' description: Channel-specific delivery configuration (email, SMS, push, etc.) content: $ref: '#/components/schemas/ElementalContent' description: Template content configuration including blocks, elements, and message structure providers: $ref: '#/components/schemas/MessageProviders' description: Provider-specific delivery configuration for routing to specific email/SMS providers routing: $ref: '#/components/schemas/MessageRouting' description: Message routing configuration for multi-channel delivery strategies required: - content PutTenantTemplateResponse: title: PutTenantTemplateResponse type: object description: Response from creating or updating a tenant notification template properties: id: type: string description: The template ID version: type: string description: The version of the saved template published_at: type: string nullable: true description: >- The timestamp when the template was published. Only present if the template was published as part of this request. required: - id - version PostTenantTemplatePublishRequest: title: PostTenantTemplatePublishRequest type: object description: Request body for publishing a tenant template version properties: version: type: string default: latest description: >- The version of the template to publish (e.g., "v1", "v2", "latest"). If not provided, defaults to "latest". PostTenantTemplatePublishResponse: title: PostTenantTemplatePublishResponse type: object description: Response from publishing a tenant template properties: id: type: string description: The template ID version: type: string description: The published version of the template published_at: type: string description: The timestamp when the template was published required: - id - version - published_at PayloadTooLarge: title: PayloadTooLarge type: object description: Error returned when the request payload exceeds the maximum allowed size properties: type: type: string enum: - invalid_request_error required: - type allOf: - $ref: '#/components/schemas/BaseError' AllowedPreference: title: AllowedPreference type: string description: A preference control a recipient may customize for a topic. enum: - snooze - channel_preferences WorkspacePreferenceTopicCreateRequest: title: WorkspacePreferenceTopicCreateRequest type: object description: Request body for creating a preference topic. properties: name: type: string description: Human-readable name for the preference topic. description: type: string nullable: true description: Optional description shown under the topic on the hosted preferences page. default_status: $ref: '#/components/schemas/SubscriptionTopicStatus' description: The default subscription status applied when a recipient has not set their own. routing_options: type: array items: $ref: '#/components/schemas/ChannelClassification' nullable: true description: Default channels delivered for this topic. Defaults to empty if omitted. allowed_preferences: type: array items: $ref: '#/components/schemas/AllowedPreference' nullable: true description: Preference controls a recipient may customize for this topic. Defaults to empty if omitted. include_unsubscribe_header: type: boolean nullable: true description: Whether to include a list-unsubscribe header on emails for this topic. topic_data: type: object additionalProperties: true nullable: true description: Arbitrary metadata associated with the topic. required: - name - default_status WorkspacePreferenceTopicReplaceRequest: title: WorkspacePreferenceTopicReplaceRequest type: object description: >- Request body for replacing a preference topic. Full document replacement; missing optional fields are cleared. properties: name: type: string description: Human-readable name for the preference topic. description: type: string nullable: true description: Optional description shown under the topic on the hosted preferences page. Omit to clear. default_status: $ref: '#/components/schemas/SubscriptionTopicStatus' description: The default subscription status applied when a recipient has not set their own. routing_options: type: array items: $ref: '#/components/schemas/ChannelClassification' nullable: true description: Default channels delivered for this topic. Omit to clear. allowed_preferences: type: array items: $ref: '#/components/schemas/AllowedPreference' nullable: true description: Preference controls a recipient may customize. Omit to clear. include_unsubscribe_header: type: boolean nullable: true description: Whether to include a list-unsubscribe header on emails for this topic. topic_data: type: object additionalProperties: true nullable: true description: Arbitrary metadata associated with the topic. Omit to clear. required: - name - default_status WorkspacePreferenceTopicGetResponse: title: WorkspacePreferenceTopicGetResponse type: object description: A subscription preference topic in your workspace. properties: id: type: string description: The preference topic id. name: type: string description: Human-readable name. description: type: string nullable: true description: Optional description shown under the topic on the hosted preferences page. default_status: $ref: '#/components/schemas/SubscriptionTopicStatus' description: The default subscription status applied when a recipient has not set their own. routing_options: type: array items: $ref: '#/components/schemas/ChannelClassification' description: Default channels delivered for this topic. May be empty. allowed_preferences: type: array items: $ref: '#/components/schemas/AllowedPreference' description: Preference controls a recipient may customize. May be empty. include_unsubscribe_header: type: boolean description: Whether a list-unsubscribe header is included on emails for this topic. topic_data: type: object additionalProperties: true description: Arbitrary metadata associated with the topic. created: type: string description: ISO-8601 timestamp of when the topic was created. creator: type: string nullable: true description: Id of the creator. updated: type: string description: ISO-8601 timestamp of the last update. updater: type: string nullable: true description: Id of the last updater. required: - id - name - default_status - routing_options - allowed_preferences - include_unsubscribe_header - topic_data - created - updated WorkspacePreferenceTopicListResponse: title: WorkspacePreferenceTopicListResponse type: object description: Topics contained in a workspace preference. properties: results: type: array items: $ref: '#/components/schemas/WorkspacePreferenceTopicGetResponse' required: - results PublishPreferencesRequest: title: PublishPreferencesRequest type: object description: >- Optional page metadata to apply when publishing the workspace's preferences page. All fields are optional; omitted fields fall back to the page defaults (and the workspace default brand). properties: heading: type: string nullable: true description: Heading shown at the top of the hosted preferences page. description: type: string nullable: true description: Description shown under the heading on the hosted preferences page. brand_id: type: string nullable: true description: >- Brand for the hosted page - "default" (workspace default brand), "none" (no brand), or a specific brand id. Defaults to "default". PublishPreferencesResponse: title: PublishPreferencesResponse type: object description: Result of publishing the workspace's preferences page. properties: page_id: type: string description: Id of the published page snapshot. published_at: type: string description: ISO-8601 timestamp of the publish. published_by: type: string nullable: true description: Id of the publisher. published_version: type: number description: Monotonic published version (epoch milliseconds). preview_url: type: string nullable: true description: Draft-mode hosted preferences page URL for previewing. required: - page_id - published_at - published_version WorkspacePreferenceCreateRequest: title: WorkspacePreferenceCreateRequest type: object description: Request body for creating a workspace preference. properties: name: type: string description: Human-readable name for the workspace preference. description: type: string nullable: true description: Optional description shown under the section on the hosted preferences page. routing_options: type: array items: $ref: '#/components/schemas/ChannelClassification' nullable: true description: Default channels for the workspace preference. Defaults to empty if omitted. has_custom_routing: type: boolean nullable: true description: Whether the workspace preference defines custom routing for its topics. required: - name WorkspacePreferenceReplaceRequest: title: WorkspacePreferenceReplaceRequest type: object description: >- Request body for replacing a workspace preference. Full document replacement; missing optional fields are cleared. properties: name: type: string description: Human-readable name for the workspace preference. description: type: string nullable: true description: Optional description shown under the section on the hosted preferences page. Omit to clear. routing_options: type: array items: $ref: '#/components/schemas/ChannelClassification' nullable: true description: Default channels for the workspace preference. Omit to clear. has_custom_routing: type: boolean nullable: true description: Whether the workspace preference defines custom routing for its topics. required: - name WorkspacePreferenceGetResponse: title: WorkspacePreferenceGetResponse type: object description: A workspace preference in your workspace, including its topics. properties: id: type: string description: The workspace preference id. name: type: string description: Human-readable name. description: type: string nullable: true description: Optional description shown under the section on the hosted preferences page. routing_options: type: array items: $ref: '#/components/schemas/ChannelClassification' description: Default channels for the workspace preference. May be empty. has_custom_routing: type: boolean description: Whether the workspace preference defines custom routing for its topics. created: type: string description: ISO-8601 timestamp of when the workspace preference was created. creator: type: string nullable: true description: Id of the creator. updated: type: string nullable: true description: ISO-8601 timestamp of the last update. updater: type: string nullable: true description: Id of the last updater. topics: type: array items: $ref: '#/components/schemas/WorkspacePreferenceTopicGetResponse' description: The topics contained in this workspace preference. required: - id - name - routing_options - has_custom_routing - created - topics WorkspacePreferenceListResponse: title: WorkspacePreferenceListResponse type: object description: The workspace's preferences, each with its topics. properties: results: type: array items: $ref: '#/components/schemas/WorkspacePreferenceGetResponse' required: - results RoutingStrategyCreateRequest: title: RoutingStrategyCreateRequest type: object description: Request body for creating a routing strategy. properties: name: type: string description: Human-readable name for the routing strategy. description: type: string nullable: true description: Optional description of the routing strategy. tags: type: array items: type: string nullable: true description: Optional tags for categorization. routing: $ref: '#/components/schemas/MessageRouting' description: Routing tree defining channel selection method and order. channels: $ref: '#/components/schemas/MessageChannels' nullable: true description: Per-channel delivery configuration. Defaults to empty if omitted. providers: $ref: '#/components/schemas/MessageProviders' nullable: true description: Per-provider delivery configuration. Defaults to empty if omitted. required: - name - routing RoutingStrategyReplaceRequest: title: RoutingStrategyReplaceRequest type: object description: >- Request body for replacing a routing strategy. Full document replacement; missing optional fields are cleared. properties: name: type: string description: Human-readable name for the routing strategy. description: type: string nullable: true description: Optional description. Omit or null to clear. tags: type: array items: type: string nullable: true description: Optional tags. Omit or null to clear. routing: $ref: '#/components/schemas/MessageRouting' description: Routing tree defining channel selection method and order. channels: $ref: '#/components/schemas/MessageChannels' nullable: true description: Per-channel delivery configuration. Omit to clear. providers: $ref: '#/components/schemas/MessageProviders' nullable: true description: Per-provider delivery configuration. Omit to clear. required: - name - routing RoutingStrategyMutationResponse: title: RoutingStrategyMutationResponse type: object deprecated: true description: >- Deprecated — mutation endpoints now return RoutingStrategyGetResponse. Retained for backward compatibility with generated SDKs. properties: id: type: string description: The routing strategy ID (rs_ prefix). required: - id RoutingStrategyGetResponse: title: RoutingStrategyGetResponse type: object description: Full routing strategy entity returned by GET. properties: id: type: string description: The routing strategy ID (rs_ prefix). name: type: string description: Human-readable name. description: type: string nullable: true description: Description of the routing strategy. tags: type: array items: type: string nullable: true description: Tags for categorization. routing: $ref: '#/components/schemas/MessageRouting' description: Routing tree defining channel selection method and order. channels: $ref: '#/components/schemas/MessageChannels' description: Per-channel delivery configuration. May be empty. providers: $ref: '#/components/schemas/MessageProviders' description: Per-provider delivery configuration. May be empty. created: type: integer format: int64 description: Epoch milliseconds when the strategy was created. creator: type: string description: User ID of the creator. updated: type: integer format: int64 nullable: true description: Epoch milliseconds of last update. updater: type: string nullable: true description: User ID of the last updater. required: - id - name - routing - channels - providers - created - creator RoutingStrategySummary: title: RoutingStrategySummary type: object description: >- Routing strategy metadata returned in list responses. Does not include routing/channels/providers content. properties: id: type: string description: The routing strategy ID (rs_ prefix). name: type: string description: Human-readable name. description: type: string nullable: true description: Description of the routing strategy. tags: type: array items: type: string nullable: true description: Tags for categorization. created: type: integer format: int64 description: Epoch milliseconds when the strategy was created. creator: type: string description: User ID of the creator. updated: type: integer format: int64 nullable: true description: Epoch milliseconds of last update. updater: type: string nullable: true description: User ID of the last updater. required: - id - name - created - creator RoutingStrategyListResponse: title: RoutingStrategyListResponse type: object description: Paginated list of routing strategy summaries. properties: paging: $ref: '#/components/schemas/Paging' results: type: array items: $ref: '#/components/schemas/RoutingStrategySummary' required: - paging - results AssociatedNotificationListResponse: title: AssociatedNotificationListResponse type: object description: Paginated list of notification templates associated with a routing strategy. properties: paging: $ref: '#/components/schemas/Paging' results: type: array items: $ref: '#/components/schemas/NotificationTemplateSummary' required: - paging - results UsersUserPreferencesListResponse: title: UsersUserPreferencesListResponse type: object properties: paging: $ref: '#/components/schemas/Paging' description: Deprecated - Paging not implemented on this endpoint items: type: array items: $ref: '#/components/schemas/UsersTopicPreference' description: The Preferences associated with the user_id. required: - paging - items UsersUserPreferencesGetResponse: title: UsersUserPreferencesGetResponse type: object properties: topic: $ref: '#/components/schemas/UsersTopicPreference' required: - topic UsersTopicPreference: title: UsersTopicPreference type: object properties: custom_routing: type: array items: $ref: '#/components/schemas/ChannelClassification' nullable: true description: The Channels a user has chosen to receive notifications through for this topic default_status: $ref: '#/components/schemas/PreferenceStatus' has_custom_routing: type: boolean nullable: true status: $ref: '#/components/schemas/PreferenceStatus' topic_id: type: string topic_name: type: string required: - default_status - status - topic_id - topic_name UsersTopicPreferenceUpdate: title: UsersTopicPreferenceUpdate type: object properties: status: $ref: '#/components/schemas/PreferenceStatus' custom_routing: type: array items: $ref: '#/components/schemas/ChannelClassification' nullable: true description: The Channels a user has chosen to receive notifications through for this topic has_custom_routing: type: boolean nullable: true required: - status UsersUserPreferencesUpdateResponse: title: UsersUserPreferencesUpdateResponse type: object properties: message: type: string example: success required: - message UsersBulkTopicPreferenceUpdate: title: UsersBulkTopicPreferenceUpdate type: object additionalProperties: false properties: topic_id: type: string description: A unique identifier associated with a subscription topic. status: type: string description: The subscription status to apply for this topic. enum: - OPTED_IN - OPTED_OUT has_custom_routing: type: boolean description: Whether the recipient has chosen specific delivery channels for this topic. custom_routing: type: array items: $ref: '#/components/schemas/ChannelClassification' description: The channels a user has chosen to receive notifications through for this topic. required: - topic_id - status UsersBulkUpdatePreferencesParams: title: UsersBulkUpdatePreferencesParams type: object additionalProperties: false properties: topics: type: array items: $ref: '#/components/schemas/UsersBulkTopicPreferenceUpdate' minItems: 1 maxItems: 50 description: The topics to create or update. Between 1 and 50 topics may be provided in a single request. required: - topics UsersBulkReplacePreferencesParams: title: UsersBulkReplacePreferencesParams type: object additionalProperties: false properties: topics: type: array items: $ref: '#/components/schemas/UsersBulkTopicPreferenceUpdate' minItems: 0 maxItems: 50 description: >- The complete set of topic overrides for the user. Up to 50 topics may be provided. Any existing override not listed here is reset to its topic default; an empty array resets every existing override. required: - topics UsersBulkPreferenceTopic: title: UsersBulkPreferenceTopic type: object description: A single topic override echoed in a bulk preference response. properties: topic_id: type: string status: type: string description: >- The applied subscription status. Echoes the requested value, so it is always OPTED_IN or OPTED_OUT. enum: - OPTED_IN - OPTED_OUT has_custom_routing: type: boolean custom_routing: type: array items: $ref: '#/components/schemas/ChannelClassification' required: - topic_id - status - has_custom_routing - custom_routing UsersBulkPreferenceError: title: UsersBulkPreferenceError type: object description: A single topic that could not be applied in a bulk preference request. properties: topic_id: type: string reason: type: string description: A human-readable explanation of why the topic could not be applied. required: - topic_id - reason UsersBulkUpdatePreferencesResponse: title: UsersBulkUpdatePreferencesResponse type: object properties: items: type: array items: $ref: '#/components/schemas/UsersBulkPreferenceTopic' description: The topics that were successfully created or updated. errors: type: array items: $ref: '#/components/schemas/UsersBulkPreferenceError' description: The topics that could not be applied, each with a reason. required: - items - errors UsersBulkReplacePreferencesResponse: title: UsersBulkReplacePreferencesResponse type: object properties: items: type: array items: $ref: '#/components/schemas/UsersBulkPreferenceTopic' description: The complete resulting set of topic overrides for the user. deleted: type: array items: type: string description: The ids of the overrides that were reset to their topic default. required: - items - deleted UsersBulkPreferenceValidationError: title: UsersBulkPreferenceValidationError type: object description: >- Returned when a bulk replace request is rejected because one or more topics are invalid. No changes are applied. properties: message: type: string errors: type: array items: $ref: '#/components/schemas/UsersBulkPreferenceError' description: Every topic that failed validation. required: - message - errors UsersListTenantsForUserResponse: title: UsersListTenantsForUserResponse type: object properties: items: type: array items: $ref: '#/components/schemas/UserTenantAssociation' nullable: true has_more: type: boolean description: Set to true when there are more pages that can be retrieved. url: type: string description: A url that may be used to generate these results. next_url: type: string nullable: true description: |- A url that may be used to generate fetch the next set of results. Defined only when `has_more` is set to true cursor: type: string nullable: true description: |- A pointer to the next page of results. Defined only when `has_more` is set to true type: type: string enum: - list description: Always set to `list`. Represents the type of this object. required: - has_more - url - type UsersProviderKey: title: UsersProviderKey type: string enum: - firebase-fcm - apn - expo - onesignal UsersTokenStatus: title: UsersTokenStatus type: string enum: - active - unknown - failed - revoked UsersPatchOp: title: UsersPatchOp type: string enum: - replace - add - remove - copy - move - test UsersDevice: title: UsersDevice type: object properties: app_id: type: string nullable: true description: Id of the application the token is used for ad_id: type: string nullable: true description: Id of the advertising identifier device_id: type: string nullable: true description: Id of the device the token is associated with platform: type: string nullable: true description: The device platform i.e. android, ios, web manufacturer: type: string nullable: true description: The device manufacturer model: type: string nullable: true description: The device model UsersTracking: title: usersTracking type: object properties: os_version: type: string nullable: true description: The operating system version ip: type: string nullable: true description: The IP address of the device lat: type: string nullable: true description: The latitude of the device long: type: string nullable: true description: The longitude of the device UsersUserToken: title: UsersUserToken type: object properties: token: type: string description: Full body of the token. Must match token in URL path parameter. provider_key: $ref: '#/components/schemas/UsersProviderKey' expiry_date: $ref: '#/components/schemas/UsersExpiryDate' nullable: true description: >- ISO 8601 formatted date the token expires. Defaults to 2 months. Set to false to disable expiration. properties: nullable: true description: Properties about the token. device: $ref: '#/components/schemas/UsersDevice' nullable: true description: Information about the device the token came from. tracking: $ref: '#/components/schemas/UsersTracking' nullable: true description: Tracking information about the device the token came from. required: - provider_key - token UsersAddSingleTokenBody: title: UsersAddSingleTokenBody type: object description: >- Request body for adding a single token. The token value itself is provided via the path parameter, so it is omitted from the body. properties: provider_key: $ref: '#/components/schemas/UsersProviderKey' expiry_date: $ref: '#/components/schemas/UsersExpiryDate' nullable: true description: >- ISO 8601 formatted date the token expires. Defaults to 2 months. Set to false to disable expiration. properties: nullable: true description: Properties about the token. device: $ref: '#/components/schemas/UsersDevice' nullable: true description: Information about the device the token came from. tracking: $ref: '#/components/schemas/UsersTracking' nullable: true description: Tracking information about the device the token came from. required: - provider_key UsersGetUserTokenResponse: title: UsersGetUserTokenResponse type: object properties: status: $ref: '#/components/schemas/UsersTokenStatus' nullable: true status_reason: type: string nullable: true description: The reason for the token status. allOf: - $ref: '#/components/schemas/UsersUserToken' UsersPatchUserTokenOpts: title: UsersPatchUserTokenOpts type: object properties: patch: type: array items: $ref: '#/components/schemas/UsersPatchOperation' required: - patch UsersPatchOperation: title: UsersPatchOperation type: object properties: op: type: string description: The operation to perform. path: type: string description: The JSON path specifying the part of the profile to operate on. value: type: string nullable: true description: The value for the operation. required: - op - path UsersExpiryDate: title: UsersExpiryDate oneOf: - type: string - type: boolean UsersGetAllTokensResponse: title: UsersGetAllTokensResponse type: object properties: tokens: type: array items: $ref: '#/components/schemas/UsersUserToken' required: - tokens description: A list of tokens registered with the user. DigestInstanceListResponse: title: DigestInstanceListResponse type: object properties: type: type: string enum: - list description: Always `list` for a paginated list response. items: type: array items: $ref: '#/components/schemas/DigestInstance' description: The digest instances for this page of results. has_more: type: boolean description: Whether there are more digest instances to fetch using the cursor. cursor: type: string nullable: true description: A cursor token for fetching the next page of results, or null when there are none. url: type: string description: The path of the current request. next_url: type: string nullable: true description: The path to fetch the next page of results, or null when there are none. required: - type - items - has_more DigestInstance: title: DigestInstance type: object properties: digest_instance_id: type: string description: A unique identifier for the digest instance. status: type: string enum: - IN_PROGRESS - COMPLETED description: >- The status of the digest instance. `IN_PROGRESS` instances are still accumulating events; `COMPLETED` instances have been released. event_count: type: integer description: The total number of events received for this instance. user_id: type: string description: The ID of the user this digest instance belongs to. tenant_id: type: string nullable: true description: The ID of the tenant this digest instance belongs to, if any. categories: type: array items: $ref: '#/components/schemas/DigestCategory' description: The categories configured for the digest. category_key_counts: type: object additionalProperties: type: integer description: A map of category key to the number of events received for that category. disabled: type: boolean description: Whether the digest instance has been disabled. created_at: type: string description: An ISO 8601 timestamp of when the digest instance was created. required: - digest_instance_id - status - event_count - user_id DigestCategory: title: DigestCategory type: object properties: category_key: type: string description: The key that identifies the category within the digest. retain: type: string enum: - first - last - highest - lowest - none description: Which events to keep when the number of events exceeds the retention limit for the category. sort_key: type: string description: The data key used to order events when `retain` is `highest` or `lowest`. required: - category_key - retain securitySchemes: BearerAuth: type: http scheme: bearer servers: - url: https://api.courier.com description: Production