SendGrid Segments API

openapi: 3.2.0
info:
  title: Twilio SendGrid Legacy Marketing Campaigns Contacts…
  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, Lists API, and Segments API to manage your contacts.


    See **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
security:
- BearerAuth: []
tags:
- name: Segments
  description: 'Twilio SendGrid Legacy Marketing Campaigns Contacts: Segments API'
paths:
  /v3/contactdb/segments:
    post:
      operationId: CreateSegment
      summary: Create a Segment
      tags:
      - Segments
      description: '**This endpoint allows you to create a new segment.**


        Valid operators for create and update depend on the type of the field for which you are searching.


        **Dates**

        - "eq", "ne", "lt" (before), "gt" (after)

        - You may use MM/DD/YYYY for day granularity or an epoch for second granularity.

        - "empty", "not_empty"

        - "is within"

        - You may use an ISO 8601 date format or the # of days.


        **Text**

        - "contains"

        - "eq" (is/equals - matches the full field)

        - "ne" (is not/not equals - matches any field where the entire field is not the condition value)

        - "empty"

        - "not_empty"


        **Numbers**

        - "eq" (is/equals)

        - "lt" (is less than)

        - "gt" (is greater than)

        - "empty"

        - "not_empty"


        **Email Clicks and Opens**

        - "eq" (opened)

        - "ne" (not opened)


        All field values must be a string.


        Conditions using "eq" or "ne" for email clicks and opens should provide a "field" of either `clicks.campaign_identifier` or `opens.campaign_identifier`.

        The condition value should be a string containing the id of a completed campaign.


        The conditions list may contain multiple conditions, joined by an "and" or "or" in the "and_or" field.


        The first condition in the conditions list must have an empty "and_or", and subsequent conditions must all specify an "and_or".'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactdbSegments'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbSegmentsId200'
              examples:
                response:
                  value:
                    id: 1
                    name: Last Name Miller
                    list_id: 4
                    conditions:
                    - field: last_name
                      value: Miller
                      operator: eq
                      and_or: ''
                    - field: last_clicked
                      value: 01/02/2015
                      operator: gt
                      and_or: and
                    - field: clicks.campaign_identifier
                      value: '513'
                      operator: eq
                      and_or: or
                    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: request body is not valid json
                    - message: invalid value is passed into one of the request body parameters
                    - field: field
                      message: field and set value is not passed into the request body
                    - field: value
                      message: value and set value is not passed into the request body
                    - field: operator
                      message: operator and set value is not passed into the request body
                    - field: and_or
                      message: and_or is not set on more than one condition and less than all conditions
                    - field: and_or
                      message: and_or is set on all conditions
                    - field: and_or
                      message: and_or is set on the only condition passed
                    - field: and_or
                      message: and_or and set value is not passed into the request body
                    - field: list_id
                      message: the list_id is not valid
                    - field: name
                      message: the name is not valid
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
    get:
      operationId: ListSegment
      summary: Retrieve all segments
      tags:
      - Segments
      description: '**This endpoint allows you to retrieve all of your segments.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: List All Segments response
                type: object
                properties:
                  segments:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactdbSegments'
                required:
                - segments
              examples:
                response:
                  value:
                    segments:
                    - id: 1234
                      name: Age segments < 25
                      conditions:
                      - field: age
                        value: '25'
                        operator: lt
                      recipient_count: 8
                    - id: 2345
                      name: email address - gmail
                      conditions:
                      - field: email
                        value: '@gmail.com'
                        operator: contains
                      recipient_count: 0
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
  /v3/contactdb/segments/{segment_id}:
    parameters:
    - name: segment_id
      in: path
      required: true
      schema:
        type: integer
    get:
      operationId: GetSegment
      summary: Retrieve a segment
      tags:
      - Segments
      description: '**This endpoint allows you to retrieve a single segment with the given ID.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbSegments'
              examples:
                response:
                  value:
                    id: 1
                    name: Last Name Miller
                    list_id: 4
                    conditions:
                    - field: last_name
                      value: Miller
                      operator: eq
                      and_or: ''
                    recipient_count: 1
        '400':
          description: The segment_id is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: if segment_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 `segment_id` does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: segment_id not found
    patch:
      operationId: UpdateSegment
      summary: Update a segment
      tags:
      - Segments
      description: '**This endpoint allows you to update a segment.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                list_id:
                  type: number
                  description: The list ID you would like this segment to be built from.
                conditions:
                  type: array
                  description: The conditions by which this segment should be created.
                  items:
                    $ref: '#/components/schemas/ContactdbSegmentsConditions'
              required:
              - name
              example:
                name: The Millers
                list_id: 5
                conditions:
                - field: last_name
                  value: Miller
                  operator: eq
                  and_or: ''
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbSegments'
              examples:
                response:
                  value:
                    id: 5
                    name: The Millers
                    list_id: 5
                    conditions:
                    - field: last_name
                      value: Miller
                      operator: eq
                      and_or: ''
                    recipient_count: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: request body is not valid json
                    - message: invalid value is passed into one of the request body parameters
                    - segment_id: segment_id
                      message: segment id is not valid
                    - field: field
                      message: field and set value is not passed into the request body
                    - field: value
                      message: value and set value is not passed into the request body
                    - field: operator
                      message: operator and set value is not passed into the request body
                    - field: and_or
                      message: and_or is not set on more than one condition and less than all conditions
                    - field: and_or
                      message: and_or is set on all conditions
                    - field: and_or
                      message: and_or is set on the only condition passed
                    - field: and_or
                      message: and_or and set value is not passed into the request body
                    - field: list_id
                      message: the list_id is not valid
                    - field: name
                      message: the name is not valid
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
    delete:
      operationId: DeleteSegment
      summary: Delete a segment
      tags:
      - Segments
      description: '**This endpoint allows you to delete a segment from your recipients database.**


        You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment.'
      parameters:
      - name: delete_contacts
        in: query
        description: True to delete all contacts matching the segment in addition to deleting the segment
        schema:
          type: boolean
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
        '400':
          description: Either segment_id or delete_contacts is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: segment_id
                      message: Returned if segment_id is not valid
                    - field: delete_contacts
                      message: Returned if delete_contacts is not a valid boolean
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
        '404':
          description: Returned if `segment_id` does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: segment_id
                      message: segment_id does not exist
  /v3/contactdb/segments/{segment_id}/recipients:
    parameters:
    - name: segment_id
      in: path
      description: The ID of the segment from which you want to retrieve recipients.
      required: true
      schema:
        type: integer
    get:
      operationId: ListRecipientForSegment
      summary: Retrieve recipients on a segment
      tags:
      - Segments
      description: '**This endpoint allows you to retrieve all of the recipients in a segment with the given ID.**'
      parameters:
      - name: page
        in: query
        schema:
          type: integer
      - name: page_size
        in: query
        schema:
          type: integer
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: List Recipients On a Segment response
                type: object
                properties:
                  recipients:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactdbRecipient200'
                required:
                - recipients
              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: Indiana
                        type: text
        '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
        '404':
          description: The segment_id is not valid or does not exist
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    ContactdbSegments:
      title: Create a Segment request
      type: object
      properties:
        name:
          type: string
          description: The name of this segment.
        list_id:
          type: integer
          description: The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list.
        conditions:
          type: array
          description: The conditions for a recipient to be included in this segment.
          items:
            $ref: '#/components/schemas/ContactdbSegmentsConditions'
        recipient_count:
          type: number
          description: The count of recipients in this list. This is not included on creation of segments.
      required:
      - name
      - conditions
      example:
        name: Last Name Miller
        list_id: 4
        conditions:
        - field: last_name
          value: Miller
          operator: eq
          and_or: ''
        - field: last_clicked
          value: 01/02/2015
          operator: gt
          and_or: and
        - field: clicks.campaign_identifier
          value: '513'
          operator: eq
          and_or: or
        recipient_count: 1234
    ContactdbRecipient200:
      title: 'ContactDB: Recipient'
      type: object
      properties:
        recipients:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: The ID of this recipient.
              created_at:
                type: number
                description: The time this record was created in your contactdb, in unixtime.
              custom_fields:
                type: array
                description: The custom fields assigned to this recipient and their values.
                items:
                  $ref: '#/components/schemas/ContactdbCustomFieldIdValue'
              email:
                type: string
                description: The email address of this recipient. This is a default custom field that SendGrid provides.
                format: email
              first_name:
                description: The first name of this recipient. This is a default custom field that SendGrid provides.
                nullable: true
                type: string
              last_name:
                description: The last name of the recipient.
                nullable: true
                type: string
              last_clicked:
                description: The last time this recipient clicked a link from one of your campaigns, in unixtime.
                nullable: true
                type: number
              last_emailed:
                description: The last time this user was emailed by one of your campaigns, in unixtime.
                nullable: true
                type: number
              last_opened:
                description: The last time this recipient opened an email from you, in unixtime.
                nullable: true
                type: number
              updated_at:
                type: number
                description: The last update date for this recipient's record.
            required:
            - email
    Type:
      type: string
      enum:
      - date
      - text
      - number
    ContactdbSegmentsId200:
      title: 'ContactDB:: Segments with ID'
      type: object
      properties:
        id:
          type: number
          description: The ID of the segment.
        name:
          type: string
          description: The name of this segment.
        list_id:
          type: integer
          description: The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list.
        conditions:
          type: array
          description: The conditions for a recipient to be included in this segment.
          items:
            $ref: '#/components/schemas/ContactdbSegmentsConditions'
        recipient_count:
          type: number
          description: The count of recipients in this list. This is not included on creation of segments.
      required:
      - conditions
      - id
      - name
    Operator:
      type: string
      enum:
      - eq
      - ne
      - lt
      - gt
      - contains
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: An error message.
              field:
                description: When applicable, this property value will be the field that generated the error.
                nullable: true
                type: string
              help:
                type: object
                description: When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error.
        id:
          type: string
          description: When applicable, this property value will be an error ID.
      example:
        errors:
        - field: field_name
          message: error message
    ContactdbSegmentsConditions:
      title: 'ContactDB: Segments: Conditions'
      type: object
      properties:
        field:
          type: string
        value:
          type: string
        operator:
          type: string
          $ref: '#/components/schemas/Operator'
        and_or:
          type: string
          $ref: '#/components/schemas/AndOr'
      required:
      - field
      - value
      - operator
    AndOr:
      type: string
      enum:
      - and
      - or
      - ''
    ContactdbCustomFieldIdValue:
      title: ContactDB Custom field schema.
      type: object
      properties:
        name:
          type: string
          description: The name of the field
        type:
          type: string
          description: The type of the field.
          $ref: '#/components/schemas/Type'
        id:
          type: number
          description: The ID of the custom field.
        value:
          description: The value of this recipient's custom field
          nullable: true
          type: string
  parameters:
    OnBehalfOf:
      name: on-behalf-of
      in: header
      description: 'The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent''s Subusers or customer accounts. You will use the parent account''s API key when using this header. When making a call on behalf of a customer account, the property value should be "account-id" followed by the customer account''s ID (e.g., `on-behalf-of: account-id <account-id>`). When making a call on behalf of a Subuser, the property value should be the Subuser''s username (e.g., `on-behalf-of: <subuser-username>`). See [**On Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.'
      required: false
      schema:
        type: string
  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.
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid