openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid Marketing Campaigns Lists API
  summary: The Twilio SendGrid Marketing Campaigns Lists API allows you to manage
    your contacts lists programmatically. Lists are static collections of Marketing
    Campaigns contacts.
  description: 'The Twilio SendGrid Marketing Campaigns Lists API allows you to manage
    your contacts lists programmatically. Lists are static collections of Marketing
    Campaigns contacts. You can use this API to interact with the list objects themselves.
    To add contacts to a list, you must use the [Contacts API](https://docs.sendgrid.com/api-reference/contacts/).


    You can also manage your lists using the Contacts menu in the [Marketing Campaigns
    application user interface](https://mc.sendgrid.com/contacts). For more information
    about lists and best practices for building them, see [**Building your Contact
    Lists**](https://sendgrid.com/docs/ui/managing-contacts/building-your-contact-list/).'
  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: mc_lists
servers:
- url: https://api.sendgrid.com
  description: The Twilio SendGrid v3 API
paths:
  /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 endpoint returns the number of contacts on a specific list.**'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact_count:
                    type: integer
                  billable_count:
                    type: integer
              examples:
                response:
                  value:
                    contact_count: 0
                    'billable_count:': 0
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    List:
      title: list
      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'
    Error:
      title: error
      type: object
      properties:
        message:
          type: string
        field:
          type: string
        error_id:
          type: string
        parameter:
          type: string
      required:
      - message
    Metadata:
      title: metadata
      type: object
      properties:
        prev:
          type: string
          format: uri
          description: The URL of the previous page of results. If this field isn't
            present, you're at the start of the list.
        self:
          type: string
          format: uri
          description: The URL of the current page of results.
        next:
          type: string
          format: uri
          description: The URL of the next page of results. If this field isn't present,
            you're at the end of the list.
        count:
          type: number
          description: The number of items in the entire list, i.e., across all pages.
    ContactDetails:
      title: contact-details2
      type: object
      properties:
        id:
          type: string
          minLength: 36
          maxLength: 36
          format: uuid
        first_name:
          type: string
        last_name:
          type: string
        unique_name:
          type: string
        email:
          type: string
          format: email
        phone_number_id:
          type: string
        external_id:
          type: string
        anonymous_id:
          type: string
        alternate_emails:
          items:
            type: string
            format: email
          nullable: true
          type: array
        address_line_1:
          type: string
        address_line_2:
          type: string
        city:
          type: string
        state_province_region:
          type: string
        country:
          type: string
        postal_code:
          type: string
        phone_number:
          type: string
        whatsapp:
          type: string
        line:
          type: string
        facebook:
          type: string
        list_ids:
          type: array
          items:
            type: string
            format: uuid
        segment_ids:
          type: array
          items:
            type: string
            format: uuid
        custom_fields:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        _metadata:
          $ref: '#/components/schemas/SelfMetadata'
      required:
      - id
      - list_ids
      - created_at
      - updated_at
    SelfMetadata:
      title: selfMetadata
      type: object
      properties:
        self:
          type: string
          description: A link to this object.
  responses: {}
  parameters: {}
  examples: {}
  requestBodies: {}
  headers: {}
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Twilio SendGrid requires you to authenticate with its APIs using
        an API key. The API key must be sent as a bearer token in the Authorization
        header.
tags:
- name: Lists
  description: Twilio SendGrid Marketing Campaigns Lists API
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid