SendGrid Recipients API

openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Recipients API
  summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts.
  description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.


    You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio SendGrid Support
    url: https://support.sendgrid.com/hc/en-us
  license:
    name: MIT
    url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
  version: 1.0.0
  x-sendgrid:
    libraryPackage: account_provisioning
servers:
- url: https://api.sendgrid.com
  description: for global users and subusers
- url: https://api.eu.sendgrid.com
  description: for EU regional subusers
security:
- BearerAuth: []
tags:
- name: Recipients
  description: 'Twilio SendGrid Legacy Marketing Campaigns Contacts: Recipients API'
paths:
  /v3/contactdb/recipients:
    post:
      operationId: AddRecipient
      summary: Add recipients
      tags:
      - Recipients
      description: '**This endpoint allows you to add a Marketing Campaigns recipient.**


        You can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides.


        The rate limit is three requests every 2 seconds. You can upload 1000  contacts per request. So the maximum upload rate is 1500 recipients per second.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  email:
                    type: string
                    description: The email address of the recipient.
                    format: email
                  first_name:
                    type: string
                    description: The first name of the recipient.
                  last_name:
                    type: string
                    description: The last name of the recipient.
                  age:
                    type: integer
                required:
                - email
              example:
              - email: example@example.com
                first_name: ''
                last_name: User
                age: 25
              - email: example2@example.com
                first_name: Example
                last_name: User
                age: 25
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbRecipientResponse201'
              examples:
                response:
                  value:
                    error_count: 1
                    error_indices:
                    - 2
                    new_count: 2
                    persisted_recipients:
                    - YUBh
                    - bWlsbGVyQG1pbGxlci50ZXN0
                    updated_count: 0
                    errors:
                    - message: Invalid email.
                      error_indices:
                      - 2
        '400':
          description: The request body is not valid json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: Request body is not valid json
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
    patch:
      operationId: UpdateRecipient
      summary: Update Recipient
      tags:
      - Recipients
      description: '**This endpoint allows you to update one or more recipients.**


        The body of an API call to this endpoint must include an array of one or more recipient objects.


        It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  email:
                    type: string
                    format: email
                  last_name:
                    type: string
                    description: The last name of the recipient. This is one of the default custom fields.
                  first_name:
                    type: string
                    description: The first name of the recipient. This is one of the default custom fields.
                required:
                - email
              example:
              - email: jones@example.com
                last_name: Jones
                first_name: Guy
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbRecipientResponse201'
        '400':
          description: The request body is not valid json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: Request body is not valid json
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
    delete:
      operationId: DeleteRecipients
      summary: Delete Recipients
      tags:
      - Recipients
      description: '**This endpoint allows you to deletes one or more recipients.**


        The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
              example:
              - recipient_id1
              - recipient_id2
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
        '400':
          description: The request was formatted incorrectly or missing required parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: No recipient ids provided
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
    get:
      operationId: ListRecipient
      summary: Retrieve recipients
      tags:
      - Recipients
      description: '**This endpoint allows you to retrieve all of your Marketing Campaigns recipients.**


        Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of

        the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.'
      parameters:
      - name: page
        in: query
        description: Page index of first recipients to return (must be a positive integer)
        schema:
          type: integer
      - name: page_size
        in: query
        description: Number of recipients to return at a time (must be a positive integer between 1 and 1000)
        schema:
          type: integer
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: List Recipients response
                type: object
                properties:
                  recipients:
                    type: array
                    items:
                      type: object
                required:
                - recipients
        '400':
          description: Input failed validation
          content:
            application/json:
              schema:
                type: object
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
  /v3/contactdb/recipients/{recipient_id}:
    parameters:
    - name: recipient_id
      in: path
      description: The ID of the recipient that you want to retrieve.
      required: true
      schema:
        type: string
    get:
      operationId: GetRecipient
      summary: Retrieve a single recipient
      tags:
      - Recipients
      description: '**This endpoint allows you to retrieve a single recipient by ID from your contact database.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbRecipient200'
        '400':
          description: Returned if `recipient_id` is not valid
          content:
            application/json:
              schema:
                type: object
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
        '404':
          description: A record for that recipient id does not exist
          content:
            application/json:
              schema:
                type: object
    delete:
      operationId: DeleteRecipient
      summary: Delete a Recipient
      tags:
      - Recipients
      description: '**This endpoint allows you to delete a single recipient with the given ID from your contact database.**


        > Use this to permanently delete your recipients from all of your contact lists and all segments if required by applicable law.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
        '400':
          description: Returned if `recipient_id` is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: recipient not found
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
        '404':
          description: A record for that recipient id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: recipient_id is not valid
  /v3/contactdb/recipients/{recipient_id}/lists:
    parameters:
    - name: recipient_id
      in: path
      description: The ID of the recipient for whom you are retrieving lists.
      required: true
      schema:
        type: string
    get:
      operationId: GetRecipientList
      summary: Retrieve the lists that a recipient is on
      tags:
      - Recipients
      description: '**This endpoint allows you to retrieve the lists that a given recipient belongs to.**


        Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  lists:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactdbList2xx'
              examples:
                response:
                  value:
                    lists:
                    - id: 1234
                      name: Example list
                      recipient_count: 42
        '400':
          description: Returned if `recipient_id` is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: recipient ID is invalid
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
        '404':
          description: Returned if a record for the recipient id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: recipient id not found
  /v3/contactdb/recipients/billable_count:
    get:
      operationId: GetBillable
      summary: Retrieve the count of billable recipients
      tags:
      - Recipients
      description: '**This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.**


        You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbRecipientCount200'
              examples:
                response:
                  value:
                    recipient_count: 1234
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
  /v3/contactdb/recipients/count:
    get:
      operationId: ListRecipientCount
      summary: Retrieve a Count of Recipients
      tags:
      - Recipients
      description: '**This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbRecipientCount200'
              examples:
                response:
                  value:
                    recipient_count: 1234
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
  /v3/contactdb/recipients/search:
    get:
      operationId: ListSearchRecipient
      summary: Search recipients
      tags:
      - Recipients
      description: '**This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.**


        field_name:


        * is a variable that is substituted for your actual custom field name from your recipient.

        * Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200)

        * If field_name is a ''reserved'' date field, such as created_at or updated_at, the system will internally convert

        your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to

        Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through

        Mon, 02 Feb 2015 23:59:59 GMT.'
      parameters:
      - name: '{field_name}'
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  recipients:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactdbRecipient200'
              examples:
                response:
                  value:
                    recipients:
                    - created_at: 1422313607
                      email: jones@example.com
                      first_name: null
                      id: YUBh
                      last_clicked: null
                      last_emailed: null
                      last_name: Jones
                      last_opened: null
                      updated_at: 1422313790
                      custom_fields:
                      - id: 23
                        name: pet
                        value: Fluffy
                        type: text
        '400':
          description: The request was formatted incorrectly or missing required parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: 'The following parameters are not custom fields or reserved fields: [{field_name}]'
                    - message: No search params are specified
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
    post:
      operationId: SearchRecipient
      summary: Search recipients
      tags:
      - Recipients
      description: "Search using segment conditions without actually creating a segment.\nBody contains a JSON object with `conditions`, a list of conditions as described below, and an optional `list_id`, which is a valid list ID for a list to limit the search on.\n\nValid operators for create and update depend on the type of the field for which you are searching.\n\n- Dates:\n  - `\"eq\"`, `\"ne\"`, `\"lt\"` (before), `\"gt\"` (after)\n    - You may use MM/DD/YYYY for day granularity or an epoch for second granularity.\n  - `\"empty\"`, `\"not_empty\"`\n  - `\"is within\"`\n    - You may use an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format or the # of days.\n- Text: `\"contains\"`, `\"eq\"` (is - matches the full field), `\"ne\"` (is not - matches any field where the entire field is not the condition value), `\"empty\"`, `\"not_empty\"`\n- Numbers: `\"eq\"`, `\"lt\"`, `\"gt\"`, `\"empty\"`, `\"not_empty\"`\n- Email Clicks and Opens: `\"eq\"` (opened), `\"ne\"` (not opened)\n\nField values must all be a string.\n\nSearch conditions using `\"eq\"` or `\"ne\"` for email clicks and opens should provide a \"field\" of either `clicks.campaign_identifier` or `opens.campaign_identifier`.\n\nThe condition value should be a string containing the id of a completed campaign.\n\nSearch conditions list may contain multiple conditions, joined by an `\"and\"` or `\"or\"` in the `\"and_or\"` field.\n\nThe first condition in the conditions list must have an empty `\"and_or\"`, and subsequent conditions must all specify an `\"and_or\"`."
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                list_id:
                  type: integer
                  format: int32
                conditions:
                  type: array
                  description: The conditions by which this segment should be created.
                  items:
                    $ref: '#/components/schemas/ContactdbSegmentsConditions'
              required:
              - list_id
              - conditions
              example:
                list_id: -27497588
                conditions:
                - and_or: ''
                  field: birthday
                  value: 01/12/1985
                  operator: eq
                - and_or: ''
                  field: birthday
                  value: 01/12/1985
                  operator: eq
                - and_or: ''
                  field: birthday
                  value: 01/12/1985
                  operator: eq
                - and_or: ''
                  field: birthday
                  value: 01/12/1985
                  operator: eq
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  recipients:
                    type: array
                    items:
                      type: object
                      properties:
                        created_at:
                          type: integer
                        email:
                          type: string
                        id:
                          type: string
                        last_emailed:
                          type: integer
                        last_clicked:
                          type: integer
                        last_opened:
                          type: integer
                        custom_fields:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                              name:
                                type: string
                              value:
                                anyOf:
                                - type: integer
                                - type: string
                              type:
                                type: string
                        updated_at:
                          type: integer
                        first_name:
                          type: string
                  recipient_count:
                    type: integer
              examples:
                response:
                  value:
                    recipients:
                    - created_at: -27901208
                      email: ut magna quis ipsum
                      id: fugiat ad adipisicing ullamco
                      last_emailed: 21626657
                    - created_at: 17466400
                      email: sunt irure
                      id: et
                      last_clicked: -23135244
                      last_opened: -44593357
                      first_name: est
                    - created_at: -34495329
                      email: reprehenderit incididunt velit Lorem esse
                      id: esse Ut ad dolore
                      last_clicked: 10164083
                      last_opened: 34443062
                    - created_at: -37030673
                      email: amet deserunt fugiat voluptate
                      id: et exercitation commodo id laborum
                      last_clicked: -10497425
                    - created_at: 3658435
                      email: labore veniam
                      id: ad pariatur esse
                      last_opened: -84227501
                      custom_fields:
                      - id: -5765608
                        name: proident pariatur
                        value: do in magna mollit
                        type: dolore ut
                      - id: -31131201
                        name: laborum mollit
                        value: 84434696
                        type: veniam
                      updated_at: -56455352
                      first_name: Ut cupidatat nulla deserunt adipisicing
                      last_clicked: -52862671
                    recipient_count: 65190677
        '400':
          description: ''
  /v3/contactdb/status:
    get:
      operationId: ListStatus
      summary: Get Recipient Upload Status
      tags:
      - Recipients
      description: '**This endpoint allows you to check the upload status of a Marketing Campaigns recipient.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          default: ''
                          description: Valid values are "worker_delay" and "worker_delay_seconds" (the second value appears only if "worker_delay" has a value of "delayed").
                        value:
                          type: string
                          default: ''
                          description: Valid values for the ID "worker_delay" are "OK" or "Delayed". Valid values for the ID "worker_delay_seconds" is the time of delay to upload.
              examples:
                response:
                  value:
                    status:
                    - id: worker_delay
                      value: delayed
                    - id: worker_delay_seconds
                      value: '75.0'
  /v3/contactdb/exports:
    post:
      operationId: ExportRecipient
      summary: Export Recipients
      tags:
      - Recipients
      description: '**Use this endpoint to export lists or segments of recipients**.


        If you would just like to have a link to the exported list sent to your email set the `notifications.email` option to `true` in the `POST` payload.


        If you would like to download the list, take the `id` that is returned and use the "Export Recipients Status" endpoint to get the `urls`. Once you have the list of URLs, make a `GET` request to each URL provided to download your CSV file(s).


        You specify the segments and or/recipient lists you wish to export by providing the relevant IDs in, respectively, the `segment_ids` and `list_ids` fields in the request body.


        The lists will be provided in either JSON or CSV files. To specify which of these you would required, set the request body `file_type` field to `json` or `csv`.


        You can also specify a maximum file size (in MB). If the export file is larger than this, it will be split into multiple files.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                list_ids:
                  description: IDs of the recipient lists you want to export.
                  type: array
                  items:
                    type: integer
                segment_ids:
                  description: IDs of the recipient segments you want to export.
                  type: array
                  items:
                    type: integer
                notifications:
                  type: object
                  properties:
                    email:
                      type: boolean
                file_type:
                  type: string
                  description: File type for export file. Choose from `json` or `csv`.
                  default: csv
                  $ref: '#/components/schemas/FileType'
                max_file_size:
                  description: The maximum size of an export file in MB. Note that when this option is specified, multiple output files may be returned from the export.
                  default: 5000
                  type: integer
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  id:
                    type: string
                    description: The ID of the export job.
                required:
                - _metadata
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecipientsError'
        '401':
          $ref: '#/components/responses/MarketingRecipients401'
        '403':
          $ref: '#/components/responses/MarketingRecipients403'
        '404':
          $ref: '#/components/responses/MarketingRecipients404'
        '500':
          $ref: '#/components/responses/MarketingRecipients500'
    get:
      operationId: ListExportRecipient
      summary: Get All Existing Exports
      tags:
      - Recipients
      description: "**Use this endpoint to retrieve details of all current exported jobs**.\n\nIt will return an array of objects, each of which records an export job in flight or recently completed. \n\nEach object's `export_type` field will tell you which kind of export it is and its `status` field will indicate what stage of processing it has reached. Exports which are `ready` will be accompanied by a `urls` field which lists the URLs of the export's downloadable files — there will be more than one if you specified a maximum file size in your initial export request.\n\nUse this endpoint if you have exports in flight but do not kno

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