The Twilio SendGrid Marketing Campaigns Segments V2 API allows you to create, edit, and delete segments as well as retrieve a list of segments or an individual segment by ID. Segments are similar to contact lists, except they update dynamically over time as information stored about your contacts or the criteria used to define your segments changes.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Marketing Campaigns Segments 2.0 API
summary: The Twilio SendGrid Marketing Campaigns Segments V2 API allows you to create,
edit, and delete segments as well as retrieve a list of segments or an individual
segment by ID.
description: 'The Twilio SendGrid Marketing Campaigns Segments V2 API allows you
to create, edit, and delete segments as well as retrieve a list of segments or
an individual segment by ID.
Segments are similar to contact lists, except they update dynamically over time
as information stored about your contacts or the criteria used to define your
segments changes. When you segment your audience, you are able to create personalized
Automation emails and Single Sends that directly address the wants and needs of
your particular audience.
Note that Twilio SendGrid checks for newly added or modified contacts who meet
a segment''s criteria on an hourly schedule. Only existing contacts who meet a
segment''s criteria will be included in the segment searches within 15 minutes.
Segments built using engagement data such as "was sent" or "clicked" will take
approximately 30 minutes to begin populating.
Segment samples and counts are refreshed approximately once per hour; they do
not update immediately. If no contacts are added to or removed from a segment
since the last refresh, the sample and UI count displayed will be refreshed at
increasing time intervals with a maximum sample and count refresh delay of 24
hours.
You can also manage your Segments with the [Marketing Campaigns application user
interface](https://mc.sendgrid.com/contacts). See [**Segmenting Your Contacts**](https://docs.sendgrid.com/ui/managing-contacts/segmenting-your-contacts)
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: mc_segments_2
servers:
- url: https://api.sendgrid.com
description: The Twilio SendGrid v3 API
paths:
/v3/marketing/segments/2.0:
post:
operationId: CreateSegment
summary: Create Segment
tags:
- Segmenting Contacts V2
description: Segment `name` has to be unique. A user can not create a new segment
with an existing segment name.
requestBody:
$ref: '#/components/requestBodies/SegmentWriteV2'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Segment2xx'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsSegmentV2'
'404':
description: ''
'429':
description: ''
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsSegmentV2'
get:
operationId: ListSegment
summary: Get List of Segments
tags:
- Segmenting Contacts V2
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 up to 50 in size, to filter segments on. Only
segments that have any of these list ids as the parent list will be retrieved.
This is different from the parameter of the same name used when creating
a segment.
required: false
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'.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AllSegments200'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsSegmentV2'
'404':
description: ''
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsSegmentV2'
/v3/marketing/segments/2.0/{segment_id}:
parameters:
- name: segment_id
in: path
required: true
schema:
type: string
patch:
operationId: UpdateSegment
summary: Update Segment
tags:
- Segmenting Contacts V2
description: Segment `name` has to be unique. A user can not create a new segment
with an existing segment name.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentUpdate'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Segment2xx'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsSegmentV2'
'429':
description: ''
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsSegmentV2'
get:
operationId: GetSegment
summary: Get Segment by ID
tags:
- Segmenting Contacts V2
description: Get Marketing Campaigns Segment by ID
parameters:
- name: contacts_sample
in: query
description: Defaults to `true`. Set to `false` to exclude the contacts_sample
in the response.
schema:
type: boolean
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Segment2xx'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsSegmentV2'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsSegmentV2'
delete:
operationId: DeleteSegment
summary: Delete segment
tags:
- Segmenting Contacts V2
description: '**This endpoint allows you to delete a segment by ID.**'
responses:
'202':
description: ''
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsSegmentV2'
'404':
description: ''
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsSegmentV2'
/v3/marketing/segments/2.0/refresh/{segment_id}:
post:
operationId: RefreshSegment
summary: Manually refresh a segment
description: Manually refresh a segment by segment ID.
tags:
- Segmenting Contacts V2
parameters:
- name: segment_id
in: path
required: true
schema:
type: string
maxLength: 36
minLength: 36
format: uuid
requestBody:
$ref: '#/components/requestBodies/SegmentRefresh'
responses:
'202':
description: The refresh was accepted and a request was sent to process.
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentRefresh202'
example:
job_id: 1588e03b-50aa-454a-97d1-e1530345a5ec
'403':
description: Endpoint is forbidden to the user because they are a free user.
'404':
description: Segment ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentError'
example:
error: Segment does not exist.
'429':
description: The user has reached their limit of 2 requests per segment
per day, 1 request per segment per hour, or 10 requests across all segments
per day.
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentError'
example:
error: Please check [our status page](https://status.sendgrid.com/)
for updates or [contact support](https://support.sendgrid.com/)
if the issue is not listed.
components:
schemas:
Metadata:
title: _metadata
type: object
properties:
prev:
type: string
format: uri
self:
type: string
format: uri
next:
type: string
format: uri
count:
type: integer
minimum: 0
AllSegments200:
title: all_segments_response
type: object
properties:
id:
type: string
minLength: 36
maxLength: 36
format: uuid
description: ID assigned to the segment when created.
name:
type: string
minLength: 1
maxLength: 100
description: Name of the segment.
contacts_count:
type: integer
description: Total number of contacts present in the segment
created_at:
type: string
description: ISO8601 timestamp of when the object was created
updated_at:
type: string
description: ISO8601 timestamp of when the object was last updated
sample_updated_at:
type: string
description: ISO8601 timestamp of when the samples were last updated
next_sample_update:
type: string
description: ISO8601 timestamp of when the samples will be next updated
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_version:
type: string
description: If not set, segment contains a query for use with Segment v1
APIs. If set to '2', segment contains a SQL query for use in v2.
_metadata:
$ref: '#/components/schemas/Metadata'
status:
$ref: '#/components/schemas/SegmentStatusResponse'
required:
- id
- name
- contacts_count
- created_at
- updated_at
- sample_updated_at
- next_sample_update
- parent_list_ids
- query_version
- status
SegmentStatusResponse:
title: segment_status_response
type: object
description: Segment status indicates whether the segment's contacts will be
updated periodically
properties:
query_validation:
type: string
description: Status of query validation. PENDING, VALID, or INVALID
error_message:
type: string
description: Describes any errors that were encountered during query validation
required:
- query_validation
SegmentRefreshRequest:
title: segment_refresh_request
required:
- user_time_zone
type: object
properties:
user_time_zone:
type: string
description: The user's timezone. The timezone is used to reset the refresh
count at midnight in the user's local time. Only [IANA time zone format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
is accepted.
example:
user_time_zone: America/Chicago
SegmentRefresh202:
title: segment_refresh_response
type: object
properties:
job_id:
type: string
description: The ID of the manual refresh job. Used only for internal purposes.
example:
job_id: 1588e03b-50aa-454a-97d1-e1530345a5ec
Segment2xx:
title: segment_response
type: object
properties:
id:
type: string
minLength: 36
maxLength: 36
format: uuid
description: ID assigned to the segment when created.
name:
type: string
minLength: 1
maxLength: 100
description: Name of the segment.
query_dsl:
type: string
description: SQL query which will filter contacts based on the conditions
provided
contacts_count:
type: integer
description: Total number of contacts present in the segment
contacts_sample:
type: array
description: A subset of all contacts that are in this segment
items:
$ref: '#/components/schemas/ContactResponse'
created_at:
type: string
description: ISO8601 timestamp of when the object was created
updated_at:
type: string
description: ISO8601 timestamp of when the object was last updated
sample_updated_at:
type: string
description: ISO8601 timestamp of when the samples were last updated
next_sample_update:
type: string
description: ISO8601 timestamp of when the samples will be next updated
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_version:
type: string
description: If not set, segment contains a Query for use with Segment v1
APIs. If set to '2', segment contains a SQL query for use in v2.
status:
$ref: '#/components/schemas/SegmentStatusResponse'
refreshes_used:
type: integer
description: The number of times a segment has been manually refreshed since
start of today in the user's timezone.
max_refreshes:
type: integer
description: The maximum number of manual refreshes allowed per day for
this segment. Currently, only 2 are allowed.
last_refreshed_at:
type: string
description: The ISO8601 timestamp when the segment was last refreshed in
UTC time.
required:
- id
- name
- query_dsl
- contacts_count
- contacts_sample
- created_at
- updated_at
- sample_updated_at
- next_sample_update
- parent_list_ids
- query_version
- status
ErrorsSegmentV2:
title: errors-seg
type: object
description: If the request is incorrect, an array of errors will be returned.
properties:
errors:
type: array
items:
type: object
properties:
field:
type: string
description: the field in the request body that is incorrect
message:
type: string
description: a description of what is specifically wrong with the
field passed in the request
required:
- field
- message
required:
- errors
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
SegmentUpdate:
title: segment_update
type: object
properties:
name:
type: string
minLength: 1
maxLength: 100
description: Name of the segment.
query_dsl:
type: string
description: SQL query which will filter contacts based on the conditions
provided
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
SegmentError:
title: error
required:
- error
type: object
properties:
error:
type: string
description: A description of the error.
responses: {}
parameters: {}
examples: {}
requestBodies:
SegmentWriteV2:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentWriteV2'
SegmentRefresh:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentRefreshRequest'
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 V2
description: Twilio SendGrid Marketing Campaigns Segments API V2
externalDocs:
description: Twilio SendGrid's official developer documentation.
url: https://www.twilio.com/docs/sendgrid