{ "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.\n\nSegments 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.\n\nNote 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.\n\nSegments built using engagement data such as \"was sent\" or \"clicked\" will take approximately 30 minutes to begin populating.\n\nSegment 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.\n\nYou 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.**\n\nThe 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.\n\n`parent_list_ids` | `no_parent_list_id` | `ids` | `result`\n-----------------:|:--------------------:|:-------------:|:-------------:\nempty | false | empty | all segments values\nlist_ids | false | empty | segments filtered by list_ids values\nlist_ids |true | empty | segments filtered by list_ids and segments with no parent list_ids empty\nempty | true | empty | segments with no parent list_ids\nanything | 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": "The segment could not be deleted. If it is still used by other resources, those resources are listed in the `resources` property of the error and must stop using the segment before it can be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentDeleteConflict" } } } }, "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" ] }, "InUseResource": { "title": "in_use_resource", "type": "object", "description": "A kind of resource that is using a segment, and so is blocking its deletion.", "properties": { "type": { "type": "string", "description": "The kind of resource using the segment. New values may be added over time, so clients should tolerate an unrecognized type.", "$ref": "#/components/schemas/Type" }, "ids": { "type": "array", "description": "The IDs of the resources of this type using the segment.", "items": { "type": "string", "format": "uuid" } } }, "required": [ "type", "ids" ] }, "SegmentDeleteConflict": { "title": "segment_delete_conflict", "type": "object", "description": "Returned when a segment cannot be deleted. A single error is returned however many kinds of resource are using the segment.", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "the field in the request that is incorrect" }, "message": { "type": "string", "description": "a description of what is specifically wrong" }, "resources": { "type": "array", "description": "When applicable, the resources currently using this segment. The segment cannot be deleted while they reference it. Absent when the request failed for any other reason.", "items": { "$ref": "#/components/schemas/InUseResource" } } }, "required": [ "field", "message" ] } } }, "required": [ "errors" ], "example": { "errors": [ { "field": "segment_id", "message": "Segment cannot be deleted because it is used by other resources.", "resources": [ { "type": "automation", "ids": [ "13646eaf-c57d-4fd4-9b1b-7d22ecb4db4e" ] }, { "type": "single_send", "ids": [ "f7deb9ea-92a3-11f1-ab0a-c2a00ce2124b" ] } ] } ] } }, "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": "abcd@gmail.com", "alternate_emails": [ "abcd@yahoo.com", "abcd@hotmail.com" ], "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." } } }, "Type": { "type": "string", "enum": [ "automation", "single_send" ] } }, "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" } }