SendGrid Lists API

openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Lists 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: Lists
  description: 'Twilio SendGrid Legacy Marketing Campaigns Contacts: Lists API'
paths:
  /v3/contactdb/lists:
    post:
      operationId: CreateContactDbList
      summary: Create a List
      tags:
      - Lists
      description: '**This endpoint allows you to create a list for your recipients.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              title: Create a List request
              type: object
              properties:
                name:
                  type: string
              required:
              - name
              example:
                name: your list name
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbList2xx'
              examples:
                response:
                  value:
                    id: 1
                    name: your list name
                    recipient_count: 0
        '400':
          description: The request was formatted incorrectly or missing required parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: Returned if request body is invalid JSON
                    - field: name
                      message: Returned if list name is not a string
                    - field: name
                      message: Returned if list name is a duplicate of an existing list or segment
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
    get:
      operationId: ListContactDbList
      summary: Retrieve all lists
      tags:
      - Lists
      description: '**This endpoint allows you to retrieve all of your recipient lists. If you don''t have any lists, an empty array will be returned.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: List All Lists response
                type: object
                properties:
                  lists:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactdbList2xx'
                required:
                - lists
              examples:
                response:
                  value:
                    lists:
                    - id: 1
                      name: the jones
                      recipient_count: 1
    delete:
      operationId: DeleteContactDbLists
      summary: Delete Multiple lists
      tags:
      - Lists
      description: '**This endpoint allows you to delete multiple recipient lists.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
              example:
              - 1
              - 2
              - 3
              - 4
      responses:
        '204':
          description: ''
        '400':
          description: All list ids are not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: list id was invalid
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
  /v3/contactdb/lists/{list_id}:
    parameters:
    - name: list_id
      in: path
      required: true
      schema:
        type: integer
    get:
      operationId: GetContactDbList
      summary: Retrieve a single list
      tags:
      - Lists
      description: '**This endpoint allows you to retrieve a single recipient list.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbList2xx'
              examples:
                response:
                  value:
                    id: 1
                    name: listname
                    recipient_count: 0
        '400':
          description: Provided `list_id` is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: invalid id
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
        '404':
          description: Provided `list_id` does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: List ID does not exist
    patch:
      operationId: UpdateContactDbList
      summary: Update a List
      tags:
      - Lists
      description: '**This endpoint allows you to update the name of one of your recipient lists.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              title: Update a List request
              type: object
              properties:
                name:
                  type: string
                  description: 'The new name for your list. '
              required:
              - name
              example:
                name: newlistname
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The ID of the list
                  name:
                    type: string
                    description: The new name for the list
                  recipient_count:
                    type: integer
                    description: The number of recipients on the list
              examples:
                response:
                  value:
                    id: 1234
                    name: 2016 iPhone Users
                    recipient_count: 0
        '400':
          description: The request was formatted incorrectly or missing required parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: invalid id
        '404':
          description: Returned if `list_id` does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: List ID does not exist
    delete:
      operationId: DeleteContactDbList
      summary: Delete a List
      tags:
      - Lists
      description: '**This endpoint allows you to delete a specific recipient list with the given ID.**'
      parameters:
      - name: delete_contacts
        in: query
        description: Adds the ability to delete all contacts on the list in addition to deleting the list.
        schema:
          type: boolean
          $ref: '#/components/schemas/DeleteContacts'
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                nullable: true
        '400':
          description: Returned if `list_id` or `delete_contacts` are not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: delete_contacts
                      message: delete_contacts not a bool
                    - field: list_id
                      message: Returned if list_id is not valid
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
        '404':
          description: Returned if `list_id` does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: 'List not found: 5'
  /v3/contactdb/lists/{list_id}/recipients:
    parameters:
    - name: list_id
      in: path
      description: The id of the list of recipients you want to retrieve.
      required: true
      schema:
        type: integer
    get:
      operationId: ListRecipientsFromContactDbList
      summary: Retrieve all recipients on a List
      tags:
      - Lists
      description: '**This endpoint allows you to retrieve all recipients on the list with the given ID.**'
      parameters:
      - name: page
        in: query
        description: Page index of first recipient to return (must be a positive integer)
        required: false
        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)
        required: false
        schema:
          type: integer
      - $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: 1433348344
                      custom_fields:
                      - id: 6234
                        name: age
                        type: number
                        value: null
                      - id: 6233
                        name: country
                        type: text
                        value: null
                      - id: 6235
                        name: fname
                        type: text
                        value: Example
                      - id: 6239
                        name: lname
                        type: text
                        value: User
                      - id: 6240
                        name: lname
                        type: text
                        value: null
                      email: example@example.com
                      first_name: Example
                      id: ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv==
                      last_clicked: 1438616117
                      last_emailed: 1438613272
                      last_name: User
                      last_opened: 1438616109
                      updated_at: 1438616119
        '400':
          description: Input failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: list_id
                      message: Returned if list_id is not a valid integer
                    - field: page
                      message: Returned if page is not a valid integer
                    - field: page
                      message: Returned if page is less than 1
                    - field: page_size
                      message: Returned if page_size is not a valid integer
                    - field: page_size
                      message: Returned if page_size is less than 1 or greater than 1000
        '404':
          description: Returned if `list_id` does not exist
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value:
                    errors:
                    - field: list_id
                      message: Returned if list_id is invalid
    post:
      operationId: AddRecipientsToContactDbList
      summary: Add Multiple Recipients to a List
      tags:
      - Lists
      description: '**This endpoint allows you to add multiple recipients to a list.**


        Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs (base64-encoded email addresses) should be passed exactly as they are returned from recipient endpoints.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
              example:
              - ZW1haWwxQGV4YW1wbGUuY29t
              - ZW1haWwyQHRlc3QubmV0
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                nullable: true
        '400':
          description: The request was formatted incorrectly or missing required parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: list_id
                      message: list_id is invalid
                    - field: recipient_id
                      message: no valid recipients were provided
                    - field: null
                      message: no recipients were added
                    - field: null
                      message: request body is invalid JSON
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
        '404':
          description: Returned if `list_id` does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: list_id
                      message: list_id does not exist
                    - field: recipient_id
                      message: recipient_id does not exist
  /v3/contactdb/lists/{list_id}/recipients/{recipient_id}:
    parameters:
    - name: list_id
      in: path
      description: The ID of the list that you want to add the recipient to.
      required: true
      schema:
        type: integer
    - name: recipient_id
      in: path
      description: The ID of the recipient you are adding to the list.
      required: true
      schema:
        type: string
    post:
      operationId: AddRecipientToContactDbList
      summary: Add a Single Recipient to a List
      tags:
      - Lists
      description: '**This endpoint allows you to add a single recipient to a list.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                nullable: true
        '400':
          description: Input failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: list_id
                      message: Returned if list_id is invalid
                    - field: recipient_id
                      message: Returned if 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: Input failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: list_id
                      message: Returned if list_id does not exist
                    - field: recipient_id
                      message: Returned if recipient_id does not exist
    delete:
      operationId: DeleteRecipientFromContactDbList
      summary: Delete a Single Recipient from a Single List
      tags:
      - Lists
      description: '**This endpoint allows you to delete a single recipient from a list.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
        '400':
          description: Input failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: list_id
                      message: Returned if list_id is invalid
                    - field: recipient_id
                      message: no valid recipients were provided
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
        '404':
          description: Returned if list_id or recipient_id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: list_id
                      message: Returned if list_id does not exist
                    - field: recipient_id
                      message: Returned if recipient_id does not exist
  /v3/marketing/lists:
    post:
      operationId: CreateMarketingList
      summary: Create List
      tags:
      - Lists
      description: '**This endpoint creates a new contacts list.**


        Once you create a list, you can use the UI to [trigger an automation](https://sendgrid.com/docs/ui/sending-email/getting-started-with-automation/#create-an-automation) every time you add a new contact to the list.


        A link to the newly created object is in `_metadata`.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Your name for your list
                  minLength: 1
                  maxLength: 100
              required:
              - name
              example:
                name: list-name
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
              examples:
                response:
                  value:
                    id: ca7a3796-e8a8-4029-9ccb-df8937940562
                    name: list-name
                    contact_count: 0
                    _metadata:
                      self: https://api.sendgrid.com/v3/marketing/lists/ca7a3796-e8a8-4029-9ccb-df8937940562
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Error'
    get:
      operationId: ListMarketingList
      summary: Get All Lists
      tags:
      - Lists
      description: '**This endpoint returns an array of all of your contact lists.**'
      parameters:
      - name: page_size
        in: query
        description: Maximum number of elements to return. Defaults to 100, returns 1000 max
        required: false
        schema:
          type: number
          minimum: 1
          maximum: 1000
          default: 100
      - name: page_token
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/List'
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
              examples:
                response:
                  value:
                    result:
                    - id: abc12312-x3y4-1234-abcd-123qwe456rty
                      name: list-name
                      contact_count: 0
                      _metadata:
                        self: https://api.sendgrid.com/v3/marketing/lists/abc12312-x3y4-1234-abcd-123qwe456rty
                    _metadata:
                      self: https://api.sendgrid.com/v3/marketing/lists?page_size=100&page_token=
  /v3/marketing/lists/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: The ID of the list on which you want to perform the operation.
      schema:
        type: string
    get:
      operationId: GetMarketingList
      summary: Get a List by ID
      tags:
      - Lists
      description: '**This endpoint returns data about a specific list.**

        Setting the optional parameter `contact_sample=true` returns the `contact_sample` in the response body. Up to 50 of the most recent contacts uploaded or attached to a list will be returned.

        The full contact count is also returned.'
      parameters:
      - name: contact_sample
        in: query
        description: Setting this parameter to the true  will cause the contact_sample to be returned
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The generated ID for your list.
                    minLength: 36
                    maxLength: 36
                  name:
                    type: string
                    description: The name you gave your list.
                  contact_count:
                    type: integer
                    description: The number of contacts currently stored on the list.
                  _metadata:
                    $ref: '#/components/schemas/SelfMetadata'
                  contact_sample:
                    $ref: '#/components/schemas/ContactDetails'
              examples:
                response:
                  value:
                    contact_count: 2
                    contact_sample:
                      id: c3445f88-5c69-4237-86e6-9ec9de958050
                      list_ids:
                      - 199abb98-0af3-4a8d-b371-6811ff85d062
                      created_at: '2620-06-16T17:03:54.867Z'
                      updated_at: '4780-12-06T06:51:30.024Z'
                    _metadata:
                      self: https://api.sendgrid.com/v3/marketing/lists/199abb98-0af3-4a8d-b371-6811ff85d062
                    id: 199abb98-0af3-4a8d-b371-6811ff85d062
                    name: list-name
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
    patch:
      operationId: UpdateMarketingList
      summary: Update List
      tags:
      - Lists
      description: '**This endpoint updates the name of a list.**'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Your name for your list.
              example:
                name: updated-list-name
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
              examples:
                response:
                  value:
                    id: abc12312-x3y4-1234-abcd-123qwe456rty
                    name: updated-list-name
                    contact_count: 0
                    _metadata:
                      self: https://api.sendgrid.com/v3/marketing/lists/abc12312-x3y4-1234-abcd-123qwe456rty
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
    delete:
      operationId: DeleteMarketingList
      summary: Delete a list
      tags:
      - Lists
      description: '**This endpoint allows you to deletes a specific list.**


        Optionally, you can also delete contacts associated to the list. The query parameter, `delete_contacts=true`, will delete the list and start an asynchronous job to delete associated contacts.'
      parameters:
      - name: delete_contacts
        in: query
        description: Flag indicates that all contacts on the list are also to be deleted.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: The delete has been accepted and is processing.
                properties:
                  job_id:
                    type: string
                    description: job_id of the async job
              examples:
                response:
                  value:
                    job_id: abc12312-x3y4-1234-abcd-123qwe456rty
        '204':
          description: ''
          content:
            application/json:
              schema:
                type: string
                description: 'The delete has been processed. '
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                required:
                - errors
  /v3/marketing/lists/{id}/contacts:
    parameters:
    - name: id
      in: path
      required: true
      description: The ID of the list on which you want to perform the operation.
      schema:
        type: string
    delete:
      operationId: DeleteContact
      summary: Remove Contacts from a List
      tags:
      - Lists
      description: '**This endpoint allows you to remove contacts from a given list.**


        The contacts will not be deleted. Only their list membership will be changed.'
      parameters:
      - name: contact_ids
        in: query
        description: Comma separated list of contact IDs that you want to remove from the specified contacts list.
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: The removal is accepted and processing.
                properties:
                  job_id:
                    type: string
                    description: job_id of the async job
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: ''
          content:
            application/json:
              schema:
                description: The specified list ID does not exist or one or more contact IDs do not exist.
  /v3/marketing/lists/{id}/contacts/count:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: ListContactCount
      summary: Get List Contact Count
      tags:
      - Lists
      description: '**This e

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