Twilio SendGrid Legacy Marketing Campaigns Contacts API

openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid Legacy Marketing Campaigns Contacts API
  summary: The Twilio SendGrid Legacy Marketing Campaigns Contacts API allows you
    to manage your marketing contacts programmatically. SendGrid recommends [moving
    to the latest version of Marketing Campaigns](https://docs.sendgrid.com/ui/sending-email/migrating-from-legacy-marketing-campaigns)
    if you are using this API.
  description: 'The Twilio SendGrid Legacy Marketing Campaigns Contacts API allows
    you to manage your marketing contacts programmatically. This API is operational,
    but we recommend using the current version of Marketing Campaigns'' [Contacts
    API](https://docs.sendgrid.com/api-reference/contacts/), [Lists API](https://docs.sendgrid.com/api-reference/lists/),
    and [Segments API](https://docs.sendgrid.com/api-reference/segmenting-contacts-v2/)
    to manage your contacts.


    See [**Migrating from Legacy Marketing Campaigns**](https://docs.sendgrid.com/ui/sending-email/migrating-from-legacy-marketing-campaigns)
    for more information.'
  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: lmc_contactdb
servers:
- url: https://api.sendgrid.com
  description: The Twilio SendGrid v3 API
paths:
  /v3/contactdb/custom_fields:
    post:
      operationId: CreateCustomField
      summary: Create a Custom Field
      tags:
      - Custom Fields
      description: '**This endpoint allows you to create a custom field.**


        **You can create up to 120 custom fields.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                type:
                  type: string
              example:
                name: pet
                type: text
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbCustomFieldId2xx'
              examples:
                response:
                  value:
                    id: 1
                    name: pet
                    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:
                    - field: null
                      message: Returned if request body is invalid JSON
                    - field: type
                      message: Returned if custom field type is invalid or not provided
                    - field: name
                      message: Returned if custom field name is not provided
    get:
      operationId: ListCustomField
      summary: Retrieve all custom fields
      tags:
      - Custom Fields
      description: '**This endpoint allows you to retrieve all custom fields.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: List All Custom Fields response
                type: object
                properties:
                  custom_fields:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactdbCustomFieldId2xx'
                required:
                - custom_fields
              examples:
                response:
                  value:
                    custom_fields:
                    - id: 6234
                      name: age
                      type: number
                    - id: 6233
                      name: country
                      type: text
                    - id: 6235
                      name: favorite_color
                      type: text
                    - id: 6239
                      name: fname
                      type: text
                    - id: 6240
                      name: lname
                      type: text
                    - id: 49439
                      name: pet
                      type: text
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
  /v3/contactdb/custom_fields/{custom_field_id}:
    parameters:
    - name: custom_field_id
      in: path
      description: The ID of the custom field that you want to retrieve.
      required: true
      schema:
        type: integer
    get:
      operationId: GetCustomField
      summary: Retrieve a Custom Field
      tags:
      - Custom Fields
      description: '**This endpoint allows you to retrieve a custom field by ID.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbCustomFieldId2xx'
              examples:
                response:
                  value:
                    id: 1
                    name: pet
                    type: text
        '400':
          description: ''
          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: The `custom_field_id` does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: Custom field ID does not exist
    delete:
      operationId: DeleteCustomField
      summary: Delete a Custom Field
      tags:
      - Custom Fields
      description: '**This endpoint allows you to delete a custom field by ID.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    message: Custom Field delete is processing.
        '400':
          description: The `custom_field_id` is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: Custom field in use by one or more segment conditions
                    - message: Custom field ID does not exist
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
        '404':
          description: The `custom_field_id` does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: Custom field ID does not exist
  /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: [email protected]
                      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/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: [email protected]
                first_name: ''
                last_name: User
                age: 25
              - email: [email protected]
                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 endp

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