Courier Events API

openapi: 3.0.1
info:
  title: Courier
  description: The Courier REST API.
  version: ''
paths:
  /send:
    post:
      description: Send a message to one or more recipients.
      operationId: send
      tags:
        - Send
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
              examples:
                Example1:
                  value:
                    requestId: 1-65f240a0-47a6a120c8374de9bcf9f22a
      summary: Send a message
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  $ref: '#/components/schemas/Message'
                  description: Defines the message to be delivered
              required:
                - message
            examples:
              Example1:
                summary: Send message with UserRecipient
                description: Default example using UserRecipient type
                value:
                  message:
                    to:
                      user_id: user_id
                    template: template_id
                    data:
                      foo: bar
              Example2:
                value:
                  message:
                    to:
                      email: [email protected]
                    template: template_id
                    data:
                      foo: bar
              Example3:
                value:
                  message:
                    to:
                      phone_number: '+1234567890'
                    template: template_id
                    data:
                      foo: bar
              Example4:
                value:
                  message:
                    to:
                      list_id: example_list
                    template: template_id
                    data:
                      foo: bar
              Example5:
                value:
                  message:
                    to:
                      user_id: example_user
                    content:
                      title: Hello {name}
                      body: How are you?
                    data:
                      name: Ben
                    routing:
                      method: single
                      channels:
                        - email
  /profiles/{user_id}:
    get:
      description: Returns the specified user profile.
      operationId: profiles_get
      tags:
        - User Profiles
      parameters:
        - name: user_id
          in: path
          description: A unique identifier representing the user associated with the requested profile.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileGetResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: Get a profile
      security:
        - BearerAuth: []
    post:
      description: >-
        Merge the supplied values with an existing profile or create a new profile if one doesn't already
        exist.
      operationId: profiles_create
      tags:
        - User Profiles
      parameters:
        - name: user_id
          in: path
          description: A unique identifier representing the user associated with the requested profile.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MergeProfileResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: Create a profile
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  type: object
                  additionalProperties: true
              required:
                - profile
    put:
      description: >-
        When using `PUT`, be sure to include all the key-value pairs required by the recipient's profile. 

        Any key-value pairs that exist in the profile but fail to be included in the `PUT` request will be 

        removed from the profile. Remember, a `PUT` update is a full replacement of the data. For partial
        updates, 

        use the [Patch](https://www.courier.com/docs/reference/profiles/patch/) request.
      operationId: profiles_replace
      tags:
        - User Profiles
      parameters:
        - name: user_id
          in: path
          description: A unique identifier representing the user associated with the requested user profile.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplaceProfileResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: Replace a profile
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  type: object
                  additionalProperties: true
              required:
                - profile
    patch:
      operationId: profiles_mergeProfile
      tags:
        - User Profiles
      parameters:
        - name: user_id
          in: path
          description: A unique identifier representing the user associated with the requested user profile.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
      summary: Update a profile
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileUpdateRequest'
    delete:
      description: Deletes the specified user profile.
      operationId: profiles_delete
      tags:
        - User Profiles
      parameters:
        - name: user_id
          in: path
          description: A unique identifier representing the user associated with the requested user profile.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: Delete a profile
      security:
        - BearerAuth: []
  /profiles/{user_id}/lists:
    get:
      description: Returns the subscribed lists for a specified user.
      operationId: profiles_getListSubscriptions
      tags:
        - User Profiles
      parameters:
        - name: user_id
          in: path
          description: A unique identifier representing the user associated with the requested user profile.
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: A unique identifier that allows for fetching the next set of message statuses.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetListSubscriptionsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: Get list subscriptions
      security:
        - BearerAuth: []
    post:
      description: Subscribes the given user to one or more lists. If the list does not exist, it will be created.
      operationId: profiles_subscribeToList
      tags:
        - User Profiles
      parameters:
        - name: user_id
          in: path
          description: A unique identifier representing the user associated with the requested user profile.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeToListsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: Subscribe to one or more lists
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeToListsRequest'
    delete:
      description: Removes all list subscriptions for given user.
      operationId: profiles_deleteListSubscription
      tags:
        - User Profiles
      parameters:
        - name: user_id
          in: path
          description: A unique identifier representing the user associated with the requested profile.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteListSubscriptionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: Delete list subscriptions
      security:
        - BearerAuth: []
  /lists:
    get:
      description: Returns all of the lists, with the ability to filter based on a pattern.
      operationId: lists_list
      tags:
        - Lists
      parameters:
        - name: cursor
          in: query
          description: A unique identifier that allows for fetching the next page of lists.
          required: false
          schema:
            type: string
            nullable: true
        - name: pattern
          in: query
          description: >-
            "A pattern used to filter the list items returned. Pattern types supported: exact match on
            `list_id` or a pattern of one or more pattern parts. you may replace a part with either: `*` to
            match all parts in that position, or `**` to signify a wildcard `endsWith` pattern match."
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGetAllResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: Get all lists
      security:
        - BearerAuth: []
  /lists/{list_id}:
    get:
      description: Returns a list based on the list ID provided.
      operationId: lists_get
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          description: A unique identifier representing the list you wish to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      summary: Get a list
      security:
        - BearerAuth: []
    put:
      description: Create or replace an existing list with the supplied values.
      operationId: lists_update
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          description: A unique identifier representing the list you wish to retrieve.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
      summary: Update a list
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListPutParams'
    delete:
      description: Delete a list by list ID.
      operationId: lists_delete
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          description: A unique identifier representing the list you wish to retrieve.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
      summary: Delete a list
      security:
        - BearerAuth: []
  /lists/{list_id}/restore:
    put:
      description: Restore a previously deleted list.
      operationId: lists_restore
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          description: A unique identifier representing the list you wish to retrieve.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
      summary: Restore a list
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
  /lists/{list_id}/subscriptions:
    get:
      description: Get the list's subscriptions.
      operationId: lists_getSubscribers
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          description: A unique identifier representing the list you wish to retrieve.
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: A unique identifier that allows for fetching the next set of list subscriptions
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGetSubscriptionsResponse'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      summary: Get the subscriptions for a list
      security:
        - BearerAuth: []
    post:
      description: >-
        Subscribes additional users to the list, without modifying existing subscriptions. If the list does
        not exist, it will be automatically created.
      operationId: lists_addSubscribers
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          description: A unique identifier representing the list you wish to retrieve.
          required: true
          schema:
            type: string
      responses:
        '202':
          description: ''
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: Add subscribers to a list
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                recipients:
                  type: array
                  items:
                    $ref: '#/components/schemas/PutSubscriptionsRecipient'
              required:
                - recipients
    put:
      description: >-
        Subscribes the users to the list, overwriting existing subscriptions. If the list does not exist, it
        will be automatically created.
      operationId: lists_updateSubscribers
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          description: A unique identifier representing the list you wish to retrieve.
          required: true
          schema:
            type: string
      responses:
        '202':
          description: ''
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: Subscribe users to a list
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                recipients:
                  type: array
                  items:
                    $ref: '#/components/schemas/PutSubscriptionsRecipient'
              required:
                - recipients
  /lists/{list_id}/subscriptions/{user_id}:
    put:
      description: >-
        Subscribe a user to an existing list (note: if the List does not exist, it will be automatically
        created).
      operationId: lists_subscribe
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          description: A unique identifier representing the list you wish to retrieve.
          required: true
          schema:
            type: string
        - name: user_id
          in: path
          description: A unique identifier representing the recipient associated with the list
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
      summary: Subscribe a single user profile to a list
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                preferences:
                  $ref: '#/components/schemas/RecipientPreferences'
                  nullable: true
    delete:
      description: Delete a subscription to a list by list ID and user ID.
      operationId: lists_unsubscribe
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          description: A unique identifier representing the list you wish to retrieve.
          required: true
          schema:
            type: string
        - name: user_id
          in: path
          description: A unique identifier representing the recipient associated with the list
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      summary: Unsubscribe a user profile from a list
      security:
        - BearerAuth: []
  /audiences/{audience_id}:
    get:
      description: Returns the specified audience by id.
      operationId: audiences_get
      tags:
        - Audiences
      parameters:
        - name: audience_id
          in: path
          description: A unique identifier representing the audience_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Audience'
      summary: Get an audience
      security:
        - BearerAuth: []
    put:
      description: Creates or updates audience.
      operationId: audiences_update
      tags:
        - Audiences
      parameters:
        - name: audience_id
          in: path
          description: A unique identifier representing the audience id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceUpdateResponse'
      summary: Update an audience
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  nullable: true
                  description: The name of the audience
                description:
                  type: string
                  nullable: true
                  description: A description of the audience
                operator:
                  $ref: '#/components/schemas/LogicalOperator'
                  nullable: true
                  description: The logical operator (AND/OR) for the top-level filter
                filter:
                  $ref: '#/components/schemas/AudienceFilterConfig'
                  nullable: true
    delete:
      description: Deletes the specified audience.
      operationId: audiences_delete
      tags:
        - Audiences
      parameters:
        - name: audience_id
          in: path
          description: A unique identifier representing the audience id
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
      summary: Delete an audience
      security:
        - BearerAuth: []
  /audiences/{audience_id}/members:
    get:
      description: Get list of members of an audience.
      operationId: audiences_listMembers
      tags:
        - Audiences
      parameters:
        - name: audience_id
          in: path
          description: A unique identifier representing the audience id
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: A unique identifier that allows for fetching the next set of members
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceMemberListResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: List audience members
      security:
        - BearerAuth: []
  /audiences:
    get:
      description: Get the audiences associated with the authorization token.
      operationId: audiences_listAudiences
      tags:
        - Audiences
      parameters:
        - name: cursor
          in: query
          description: A unique identifier that allows for fetching the next set of audiences
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceListResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: List all audiences
      security:
        - BearerAuth: []
  /messages:
    get:
      description: Fetch the statuses of messages you've previously sent.
      operationId: messages_list
      tags:
        - Sent Messages
      parameters:
        - name: archived
          in: query
          description: A boolean value that indicates whether archived messages should be included in the response.
          required: false
          schema:
            type: boolean
            nullable: true
        - name: cursor
          in: query
          description: A unique identifier that allows for fetching the next set of messages.
          required: false
          schema:
            type: string
            nullable: true
        - name: event
          in: query
          description: A unique identifier representing the event that was used to send the event.
          required: false
          schema:
            type: string
            nullable: true
        - name: list
          in: query
          description: A unique identifier representing the list the message was sent to.
          required: false
          schema:
            type: string
            nullable: true
        - name: messageId
          in: query
          description: A unique identifier representing the message_id returned from either /send or /send/list.
          required: false
          schema:
            type: string
            nullable: true
        - name: notification
          in: query
          description: A unique identifier representing the notification that was used to send the event.
          required: false
          schema:
            type: string
            nullable: true
        - name: provider
          in: query
          description: >-
            The key assocated to the provider you want to filter on. E.g., sendgrid, inbox, twilio, slack,
            msteams, etc. Allows multiple values to be set in query parameters.
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: recipient
          in: query
          description: A unique identifier representing the recipient associated with the requested profile.
          required: false
          schema:
            type: string
            nullable: true
        - name: status
          in: query
          description: >-
            An indicator of the current status of the message. Allows multiple values to be set in query
            parameters.
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: tag
          in: query
          description: >-
            A tag placed in the metadata.tags during a notification send. Allows multiple values to be set in
            query parameters.
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: tags
          in: query
          description: >-
            A comma delimited list of 'tags'. Messages will be returned if they match any of the tags passed
            in.
          required: false
          schema:
            type: string
            nullable: true
        - name: tenant_id
          in: query
          description: Messages sent with the context of a Tenant
          required: false
          schema:
            type: string
            nullable: true
        - name: enqueued_after
          in: query
          description: The enqueued datetime of a message to filter out messages received before.
          required: false
          schema:
            type: string
            nullable: true
        - name: traceId
          in: query
          description: The unique identifier used to trace the requests
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMessagesResponse'
      summary: List messages
      security:
        - BearerAuth: []
  /messages/{message_id}:
    get:
      description: Fetch the status of a message you've previously sent.
      operationId: messages_get
      tags:
        - Sent Messages
      parameters:
        - name: message_id
          in: path
          description: A unique identifier associated with the message you wish to retrieve (results from a send).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageDetailsExtended'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageNotFound'
      summary: Get message
      security:
        - BearerAuth: []
  /messages/{message_id}/cancel:
    post:
      description: >-
        Cancel a message that is currently in the process of being delivered. A well-formatted API call to the
        cancel message API will return either `200` status code for a successful cancellation or `409` status
        code for an unsuccessful cancellation. Both cases will include the actual message record in the
        response body (see details below).
      operationId: messages_cancel
      tags:
        - Sent Messages
      parameters:
        - name: message_id
          in: path
          description: A unique identifier representing the message ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageDetails'
      summary: Cancel message
      security:
        - BearerAuth: []
  /messages/{message_id}/history:
    get:
      description: Fetch the array of events of a message you've previously sent.
      operationId: messages_getHistory
      tags:
        - Sent Messages
      parameters:
        - name: message_id
          in: path
          description: A unique identifier representing the message ID
          required: true
          schema:
            type: string
        - name: type
          in: query
          description: A supported Message History type that will filter the events returned.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageHistoryResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageNotFound'
      summary: Get message history
      security:
        - BearerAuth: []
  /messages/{message_id}/output:
    get:
      operationId: messages_getContent
      tags:
        - Sent Messages
      parameters:
        - name: message_id
          in: path
          description: A unique identifier associated with the message you wish to retrieve (results from a send).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderOutputResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageNotFound'
      summary: Get message content
      security:
        - BearerAuth: []
  /requests/{request_id}/archive:
    put:
      operationId: messages_archive
      tags:
        - 

# --- truncated at 32 KB (272 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/courier/refs/heads/main/openapi/courier-openapi.yml