This API was deprecated on December 31, 2022. Following deprecation, all segments created in the Marketing Campaigns user interface began using the [Segmentation v2 API](https://docs.sendgrid.com/api-reference/segmenting-contacts-v2). To enable manual migration and data retrieval, this API's GET and DELETE operations will remain available.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Marketing Campaigns Segments API
summary: This API was deprecated on December 31, 2022. The GET and DELETE operations
are documented here to facilitate manual migration of your Segments to the new
API.
description: 'This API was deprecated on December 31, 2022. Following deprecation,
all segments created in the Marketing Campaigns user interface began using the
[Segmentation v2 API](https://docs.sendgrid.com/api-reference/segmenting-contacts-v2).
To enable manual migration and data retrieval, this API''s GET and DELETE operations
will remain available. The POST (create) and PATCH (update) endpoints were removed
on January 31, 2023 because it is no longer possible to create new v1 segments
or modify existing ones. See our [Segmentation v1 to v2 upgrade instructions](https://docs.sendgrid.com/for-developers/sending-email/getting-started-the-marketing-campaigns-v2-segmentation-api#upgrade-a-v1-segment-to-v2)
to manually migrate your segments to the v2 API.'
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_segments
servers:
- url: https://api.sendgrid.com
description: The Twilio SendGrid v3 API
paths:
/v3/marketing/segments:
get:
operationId: ListSegment
summary: Get List of Segments
tags:
- Segmenting Contacts
description: '**This endpoint allows you to retrieve a list of segments.**
The query param `parent_list_ids` is treated as a filter. Any match will
be returned. Zero matches will return a response code of 200 with an empty
`results` array.
`parent_list_ids` | `no_parent_list_id` | `ids` | `result`
-----------------:|:--------------------:|:-------------:|:-------------:
empty | false | empty | all segments values
list_ids | false | empty | segments filtered by list_ids values
list_ids |true | empty | segments filtered by list_ids and segments with no
parent list_ids empty
empty | true | empty | segments with no parent list_ids
anything | anything | ids | segments with matching segment ids |'
parameters:
- name: ids
in: query
description: A list of segment IDs to retrieve. When this parameter is included,
the `no_parent_list_ids` and `parent_list_ids` parameters are ignored and
only segments with given IDs are returned.
required: false
schema:
type: array
items:
type: string
- name: parent_list_ids
in: query
description: A comma separated list of list ids to be used when searching
for segments with the specified parent_list_id, no more than 50 is allowed
schema:
type: string
- name: no_parent_list_id
in: query
description: If set to `true` segments with an empty value of `parent_list_id`
will be returned in the filter. If the value is not present it defaults
to 'false'.
schema:
type: boolean
default: false
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
results:
type: array
uniqueItems: true
minItems: 0
items:
$ref: '#/components/schemas/SegmentSummary'
required:
- results
examples:
response:
value:
results:
- id: 12099613-91e5-4d09-a900-df7626325288
contacts_count: 78434802
created_at: '2921-01-27T19:33:36.479Z'
sample_updated_at: '4685-11-26T07:05:04.660Z'
updated_at: '2883-07-10T13:13:37.697Z'
- id: 60c37015-3734-4c8e-b293-68cfa2ae4fa5
contacts_count: 34177253
created_at: '2575-07-26T23:17:20.984Z'
sample_updated_at: '3074-09-04T09:49:58.127Z'
updated_at: '5116-10-15T07:37:40.838Z'
parent_list_id: fd38af3d-3f69-4947-8dca-5fa967e7be82
name: amet
'401':
$ref: '#/components/responses/Segments401'
'403':
$ref: '#/components/responses/Segments403'
'404':
$ref: '#/components/responses/Segments404'
'500':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
required:
- errors
/v3/marketing/segments/{segment_id}:
parameters:
- name: segment_id
in: path
required: true
schema:
type: string
format: uuid
minLength: 36
maxLength: 36
get:
operationId: GetSegment
summary: Get Segment by ID
tags:
- Segmenting Contacts
description: '**This endpoint allows you to retrieve a single segment by ID.**'
parameters:
- name: query_json
in: query
description: Defaults to `false`. Set to `true` to return the parsed SQL
AST as a JSON object in the field `query_json`
schema:
type: boolean
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/FullSegment'
examples:
response:
value:
id: 3b049926-0a54-4a91-83f0-086ace63c530
contacts_count: -83213117
created_at: '2921-01-27T19:33:36.479Z'
sample_updated_at: '3407-09-25T04:25:02.140Z'
updated_at: '4389-06-21T16:59:51.403Z'
contacts_sample:
- id: e70eac25-1431-4231-bccd-1cfab432301e
email: [email protected]
alternate_emails:
- [email protected]
first_name: ullamco esse culpa do
last_name: officia laboris veniam consequat
address_line_1: in occaecat labore est tempor
address_line_2: magna adipisicing
city: "\u019E\xF3"
state_province_region: culpa ut
postal_code: -75218567
country: voluptate in in reprehenderit aliquip
custom_fields:
custom_field_name1: amet deserunt mollit
custom_field_name2: minim consequat id
- id: db637d33-bce1-462c-ae9c-91ec4f761de6
email: [email protected]
alternate_emails:
- [email protected]
- [email protected]
- [email protected]
- [email protected]
- [email protected]
first_name: ea et eu
last_name: velit Ut laborum ipsu
address_line_1: labore
address_line_2: non
city: "\u0114\u0238\u0105\x9F\xC2\xB8\u0220\u024Fb\u0244"
state_province_region: deserunt dolore
postal_code: -95171713
country: do
list_ids:
- c712288b-2300-4069-bef4-2e05b5948ec3
- 9003ef29-5eb7-4951-898b-1b102e490d6e
custom_fields:
custom_field_name1: amet deserunt mollit
custom_field_name2: minim consequat id
name: enim et anim
query_dsl: nostrud
'401':
$ref: '#/components/responses/Segments401'
'403':
$ref: '#/components/responses/Segments403'
'404':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
field:
type: string
required:
- message
- field
required:
- errors
'500':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
required:
- errors
delete:
operationId: DeleteSegment
summary: Delete Segment
tags:
- Segmenting Contacts
description: '**This endpoint allows you to delete a segment by `segment_id`.**
Note that deleting a segment does not delete the contacts associated with
the segment by default. Contacts associated with a deleted segment will remain
in your list of all contacts and any other segments they belong to.'
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
$ref: '#/components/responses/Segments401'
'403':
$ref: '#/components/responses/Segments403'
'404':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
field:
type: string
required:
- message
- field
required:
- errors
'500':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
required:
- errors
components:
schemas:
FullSegment:
title: full_segment
example:
id: 58567a46-305e-48d1-b4f8-a006c906920e
contacts_count: 9266921
created_at: '2085-08-08T21:07:05.692Z'
sample_updated_at: '3407-09-25T04:25:02.140Z'
updated_at: '4431-05-07T22:23:22.352Z'
contacts_sample:
- id: c1183ada-b784-49ac-9b1f-50e73578a6dc
email: [email protected]
external_id: '1234'
alternate_emails:
- [email protected]
- [email protected]
- [email protected]
- [email protected]
first_name: est
last_name: eiusmod in laboris velit cupidatat
address_line_1: sunt aliqua
address_line_2: sit proident Lorem veniam labore
city: "\x9C\u020E\u0163\u0238\xDB\t\u010D\vC\u0141"
state_province_region: ut proident
postal_code: 30296612
country: do reprehenderit qui
custom_fields:
custom_field_name2: in consectetur ut aliqua sint
custom_field_name1: esse
name: culpa
query_dsl: cillum eiusmod
parent_list_id: 2357714d-3d82-4c80-826c-b44a4147f81c
next_sample_update: ''
type: object
properties:
id:
type: string
minLength: 36
maxLength: 36
format: uuid
contacts_count:
type: integer
created_at:
type: string
description: 'ISO8601 of created timestamp
'
format: date-time
name:
type: string
minLength: 1
maxLength: 100
description: Name of the segment.
parent_list_id:
type: string
minLength: 36
maxLength: 36
format: uuid
description: The id of the list if this segment is a child of a list. This
implies the query `AND CONTAINS(list_ids, ${parent_list_id})`
sample_updated_at:
type: string
description: ISO8601 timestamp the sample was last updated
format: date-time
updated_at:
type: string
description: ISO8601 timestamp the object was last updated
format: date-time
next_sample_update:
type: string
description: ISO8601 string that is equal to `sample_updated_at` plus an
internally calculated offset that depends on how often contacts enter
or exit segments as the scheduled pipeline updates the samples.
contacts_sample:
type: array
items:
$ref: '#/components/schemas/ContactResponse'
query_json:
type: object
description: AST representation of the query DSL
parent_list_ids:
type: array
description: The array of list ids to filter contacts on when building this
segment. It allows only one such list id for now. We will support more
in future
uniqueItems: true
items:
type: string
query_dsl:
type: string
description: SQL query which will filter contacts based on the conditions
provided
required:
- contacts_count
- contacts_sample
- created_at
- id
- name
- query_dsl
- sample_updated_at
- updated_at
SegmentSummary:
title: segment_summary
type: object
properties:
id:
type: string
minLength: 36
maxLength: 36
format: uuid
contacts_count:
type: integer
created_at:
type: string
description: 'ISO8601 of created timestamp
'
format: date-time
name:
type: string
minLength: 1
maxLength: 100
parent_list_id:
type: string
minLength: 36
maxLength: 36
format: uuid
description: The id of the list if this segment is a child of a list. This
implies the query `AND CONTAINS(list_ids, ${parent_list_id})`
sample_updated_at:
type: string
description: ISO8601 timestamp the sample was last updated
format: date-time
updated_at:
type: string
description: ISO8601 timestamp the object was last updated
format: date-time
next_sample_update:
type: string
description: ISO8601 string that is equal to `sample_updated_at` plus an
internally calculated offset that depends on how often contacts enter
or exit segments as the scheduled pipeline updates the samples.
required:
- id
- contacts_count
- created_at
- sample_updated_at
- updated_at
ContactResponse:
title: contact_response
type: object
properties:
id:
type: string
maxLength: 36
pattern: '[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}'
format: uuid
description: ID assigned to a contact when added to the system.
email:
type: string
minLength: 3
maxLength: 254
format: email
description: Email of the contact. This is a reserved field.
phone_number_id:
type: string
description: The contact's Phone Number ID. This must be a valid phone number.
external_id:
type: string
description: The contact's External ID.
maxLength: 254
anonymous_id:
type: string
description: The contact's Anonymous ID.
maxLength: 254
alternate_emails:
type: array
uniqueItems: true
minItems: 0
description: Alternate emails of the contact. This is a reserved field.
items:
type: string
minLength: 3
maxLength: 254
format: email
first_name:
type: string
minLength: 1
description: First name of the contact. This is a reserved field.
last_name:
type: string
minLength: 1
description: Last name of the contact. This is a reserved field.
address_line_1:
type: string
minLength: 0
description: First line of address of the contact. This is a reserved field.
address_line_2:
type: string
minLength: 0
description: Second line of address of the contact. This is a reserved field.
city:
type: string
minLength: 0
pattern: ^[a-zA-Z\u0080-\u024F\s\/\-\)\(\`\.\"\']+$
description: City associated with the contact. This is a reserved field.
state_province_region:
type: string
minLength: 0
description: State associated with the contact. This is a reserved field.
postal_code:
type: integer
description: Zipcode associated with the address of the contact. This is
a reserved field.
country:
type: string
minLength: 0
description: Country associated with the address of the contact. This is
a reserved field.
list_ids:
type: array
uniqueItems: true
description: IDs of all lists the contact is part of
items:
type: string
format: uuid
custom_fields:
type: object
minProperties: 0
description: The user may choose to create up to 120 custom fields or none
at all. This is not a reserved field.
properties:
custom_field_name1:
type: string
minLength: 0
custom_field_name2:
type: string
minLength: 0
segment_ids:
type: array
uniqueItems: true
description: IDs of all segments the contact is part of
items:
type: string
format: uuid
required:
- id
- alternate_emails
- first_name
- last_name
- address_line_1
- address_line_2
- city
- state_province_region
- postal_code
- country
- custom_fields
example:
id: 47d23ab0-d895-4359-a0d1-ffc7a6fc7e70
email: [email protected]
alternate_emails:
- [email protected]
- [email protected]
first_name: Ab
last_name: Cd
address_line_1: street address / P.O. box / CompanyName / c/o
address_line_2: apartment, suite, unit, building, floor etc
city: Redwood City
state_province_region: CA
postal_code: 94063
country: USA
custom_fields:
custom_field_name1: custom_field_value1
custom_field_name2: custom_field_value2
SegmentWriteV2:
title: segment_write
type: object
properties:
name:
type: string
minLength: 1
maxLength: 100
description: Name of the segment.
parent_list_ids:
type: array
description: The array of list ids to filter contacts on when building this
segment. It allows only one such list id for now. We will support more
in future
uniqueItems: true
items:
type: string
query_dsl:
type: string
description: SQL query which will filter contacts based on the conditions
provided
required:
- name
- query_dsl
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
responses:
Segments401:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Segments403:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Segments404:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
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: Segmenting Contacts
description: Twilio SendGrid Marketing Campaigns Segments API
externalDocs:
description: Twilio SendGrid's official developer documentation.
url: https://www.twilio.com/docs/sendgrid