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: KLTF@SurgGzlAxCPOqhOUHYNBLsfpfE.trh alternate_emails: - dTeJZgU5uN9UYSo@nfIB.ijxg 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: t7N5TjDmKhC0@gfdifW.ua alternate_emails: - gQol@Xcfilli.hc - n4K7OdaVQh@YfsnF.ie - TdnvS3nMStREn@miFjGzNDCPZWhiswJNxrFnOYdUAZEpesQ.yxpu - xRzGDTTzzbYK@eJ.wpgb - iI1rOpx2ct@aZhuYGZBxJLZ.phr 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: ft88@d.izxx external_id: '1234' alternate_emails: - yKDUP11FDch@QoU.vwy - ZNSN5@czAMqPi.at - 7wr51kFVVKlcBSH@DWxOueOZepetzBrku.qosk - iib-ObtO7Fxz5@vLJPRIFKPOqJGCEqcIDab.ypn 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: 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 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