openapi: 3.1.0 security: - BearerAuth: [] info: title: Twilio SendGrid Legacy Marketing Campaigns Contacts API 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](https://docs.sendgrid.com/api-reference/contacts/), [Lists API](https://docs.sendgrid.com/api-reference/lists/), and [Segments API](https://docs.sendgrid.com/api-reference/segmenting-contacts-v2/) to manage your contacts. See [**Migrating from Legacy Marketing Campaigns**](https://docs.sendgrid.com/ui/sending-email/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 paths: /v3/contactdb/custom_fields: post: operationId: CreateCustomField summary: Create a Custom Field tags: - Custom Fields description: '**This endpoint allows you to create a custom field.** **You can create up to 120 custom fields.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' requestBody: content: application/json: schema: type: object properties: name: type: string type: type: string example: name: pet type: text responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/ContactdbCustomFieldId2xx' examples: response: value: id: 1 name: pet type: text '400': description: The request was formatted incorrectly or missing required parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: Returned if request body is invalid JSON - field: type message: Returned if custom field type is invalid or not provided - field: name message: Returned if custom field name is not provided get: operationId: ListCustomField summary: Retrieve all custom fields tags: - Custom Fields description: '**This endpoint allows you to retrieve all custom fields.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: title: List All Custom Fields response type: object properties: custom_fields: type: array items: $ref: '#/components/schemas/ContactdbCustomFieldId2xx' required: - custom_fields examples: response: value: custom_fields: - id: 6234 name: age type: number - id: 6233 name: country type: text - id: 6235 name: favorite_color type: text - id: 6239 name: fname type: text - id: 6240 name: lname type: text - id: 49439 name: pet type: text '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required /v3/contactdb/custom_fields/{custom_field_id}: parameters: - name: custom_field_id in: path description: The ID of the custom field that you want to retrieve. required: true schema: type: integer get: operationId: GetCustomField summary: Retrieve a Custom Field tags: - Custom Fields description: '**This endpoint allows you to retrieve a custom field by ID.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ContactdbCustomFieldId2xx' examples: response: value: id: 1 name: pet type: text '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: invalid id '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required '404': description: The `custom_field_id` does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: Custom field ID does not exist delete: operationId: DeleteCustomField summary: Delete a Custom Field tags: - Custom Fields description: '**This endpoint allows you to delete a custom field by ID.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '202': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: message: Custom Field delete is processing. '400': description: The `custom_field_id` is not valid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: Custom field in use by one or more segment conditions - message: Custom field ID does not exist '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required '404': description: The `custom_field_id` does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: Custom field ID does not exist /v3/contactdb/lists: post: operationId: CreateContactDbList summary: Create a List tags: - Lists description: '**This endpoint allows you to create a list for your recipients.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' requestBody: content: application/json: schema: title: Create a List request type: object properties: name: type: string required: - name example: name: your list name responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/ContactdbList2xx' examples: response: value: id: 1 name: your list name 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: - field: null message: Returned if request body is invalid JSON - field: name message: Returned if list name is not a string - field: name message: Returned if list name is a duplicate of an existing list or segment '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required get: operationId: ListContactDbList summary: Retrieve all lists tags: - Lists description: '**This endpoint allows you to retrieve all of your recipient lists. If you don''t have any lists, an empty array will be returned.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: title: List All Lists response type: object properties: lists: type: array items: $ref: '#/components/schemas/ContactdbList2xx' required: - lists examples: response: value: lists: - id: 1 name: the jones recipient_count: 1 delete: operationId: DeleteContactDbLists summary: Delete Multiple lists tags: - Lists description: '**This endpoint allows you to delete multiple recipient lists.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' requestBody: content: application/json: schema: type: array items: type: integer example: - 1 - 2 - 3 - 4 responses: '204': description: '' '400': description: All list ids are not valid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: list id was invalid '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required /v3/contactdb/lists/{list_id}: parameters: - name: list_id in: path required: true schema: type: integer get: operationId: GetContactDbList summary: Retrieve a single list tags: - Lists description: '**This endpoint allows you to retrieve a single recipient list.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ContactdbList2xx' examples: response: value: id: 1 name: listname recipient_count: 0 '400': description: Provided `list_id` is not valid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: invalid id '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required '404': description: Provided `list_id` does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: List ID does not exist patch: operationId: UpdateContactDbList summary: Update a List tags: - Lists description: '**This endpoint allows you to update the name of one of your recipient lists.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' requestBody: content: application/json: schema: title: Update a List request type: object properties: name: type: string description: 'The new name for your list. ' required: - name example: name: newlistname responses: '200': description: '' content: application/json: schema: type: object properties: id: type: integer description: The ID of the list name: type: string description: The new name for the list recipient_count: type: integer description: The number of recipients on the list examples: response: value: id: 1234 name: 2016 iPhone Users 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: invalid id '404': description: Returned if `list_id` does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: List ID does not exist delete: operationId: DeleteContactDbList summary: Delete a List tags: - Lists description: '**This endpoint allows you to delete a specific recipient list with the given ID.**' parameters: - name: delete_contacts in: query description: Adds the ability to delete all contacts on the list in addition to deleting the list. schema: type: boolean $ref: '#/components/schemas/DeleteContacts' - $ref: '#/components/parameters/OnBehalfOf' responses: '202': description: '' content: application/json: schema: nullable: true '400': description: Returned if `list_id` or `delete_contacts` are not valid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: delete_contacts message: delete_contacts not a bool - field: list_id message: Returned if list_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 `list_id` does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: 'List not found: 5' /v3/contactdb/lists/{list_id}/recipients: parameters: - name: list_id in: path description: The id of the list of recipients you want to retrieve. required: true schema: type: integer get: operationId: ListRecipientsFromContactDbList summary: Retrieve all recipients on a List tags: - Lists description: '**This endpoint allows you to retrieve all recipients on the list with the given ID.**' parameters: - name: page in: query description: Page index of first recipient to return (must be a positive integer) required: false schema: type: integer - name: page_size in: query description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) required: false schema: type: integer - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: type: object properties: recipients: type: array items: $ref: '#/components/schemas/ContactdbRecipient200' examples: response: value: recipients: - created_at: 1433348344 custom_fields: - id: 6234 name: age type: number value: null - id: 6233 name: country type: text value: null - id: 6235 name: fname type: text value: Example - id: 6239 name: lname type: text value: User - id: 6240 name: lname type: text value: null email: example@example.com first_name: Example id: ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv== last_clicked: 1438616117 last_emailed: 1438613272 last_name: User last_opened: 1438616109 updated_at: 1438616119 '400': description: Input failed validation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: list_id message: Returned if list_id is not a valid integer - field: page message: Returned if page is not a valid integer - field: page message: Returned if page is less than 1 - field: page_size message: Returned if page_size is not a valid integer - field: page_size message: Returned if page_size is less than 1 or greater than 1000 '404': description: Returned if `list_id` does not exist content: application/json: schema: type: object examples: response: value: errors: - field: list_id message: Returned if list_id is invalid post: operationId: AddRecipientsToContactDbList summary: Add Multiple Recipients to a List tags: - Lists description: '**This endpoint allows you to add multiple recipients to a list.** Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs (base64-encoded email addresses) should be passed exactly as they are returned from recipient endpoints.' parameters: - $ref: '#/components/parameters/OnBehalfOf' requestBody: content: application/json: schema: type: array items: type: string example: - ZW1haWwxQGV4YW1wbGUuY29t - ZW1haWwyQHRlc3QubmV0 responses: '201': description: '' content: application/json: schema: nullable: true '400': description: The request was formatted incorrectly or missing required parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: list_id message: list_id is invalid - field: recipient_id message: no valid recipients were provided - field: null message: no recipients were added - field: null message: request body is invalid JSON '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required '404': description: Returned if `list_id` does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: list_id message: list_id does not exist - field: recipient_id message: recipient_id does not exist /v3/contactdb/lists/{list_id}/recipients/{recipient_id}: parameters: - name: list_id in: path description: The ID of the list that you want to add the recipient to. required: true schema: type: integer - name: recipient_id in: path description: The ID of the recipient you are adding to the list. required: true schema: type: string post: operationId: AddRecipientToContactDbList summary: Add a Single Recipient to a List tags: - Lists description: '**This endpoint allows you to add a single recipient to a list.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '201': description: '' content: application/json: schema: nullable: true '400': description: Input failed validation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: list_id message: Returned if list_id is invalid - field: recipient_id message: Returned if recipient_id is invalid '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required '404': description: Input failed validation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: list_id message: Returned if list_id does not exist - field: recipient_id message: Returned if recipient_id does not exist delete: operationId: DeleteRecipientFromContactDbList summary: Delete a Single Recipient from a Single List tags: - Lists description: '**This endpoint allows you to delete a single recipient from a list.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '204': description: '' '400': description: Input failed validation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: list_id message: Returned if list_id is invalid - field: recipient_id message: no valid recipients were provided '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required '404': description: Returned if list_id or recipient_id does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: list_id message: Returned if list_id does not exist - field: recipient_id message: Returned if recipient_id does not exist /v3/contactdb/recipients: post: operationId: AddRecipient summary: Add recipients tags: - Recipients description: '**This endpoint allows you to add a Marketing Campaigns recipient.** You can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides. The rate limit is three requests every 2 seconds. You can upload 1000 contacts per request. So the maximum upload rate is 1500 recipients per second.' parameters: - $ref: '#/components/parameters/OnBehalfOf' requestBody: content: application/json: schema: type: array items: type: object properties: email: type: string description: The email address of the recipient. format: email first_name: type: string description: The first name of the recipient. last_name: type: string description: The last name of the recipient. age: type: integer required: - email example: - email: example@example.com first_name: '' last_name: User age: 25 - email: example2@example.com first_name: Example last_name: User age: 25 responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/ContactdbRecipientResponse201' examples: response: value: error_count: 1 error_indices: - 2 new_count: 2 persisted_recipients: - YUBh - bWlsbGVyQG1pbGxlci50ZXN0 updated_count: 0 errors: - message: Invalid email. error_indices: - 2 '400': description: The request body is not valid json content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: Request body is not valid json '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required patch: operationId: UpdateRecipient summary: Update Recipient tags: - Recipients description: '**This endpoint allows you to update one or more recipients.** The body of an API call to this endpoint must include an array of one or more recipient objects. It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides.' parameters: - $ref: '#/components/parameters/OnBehalfOf' requestBody: content: application/json: schema: type: array items: type: object properties: email: type: string format: email last_name: type: string description: The last name of the recipient. This is one of the default custom fields. first_name: type: string description: The first name of the recipient. This is one of the default custom fields. required: - email example: - email: jones@example.com last_name: Jones first_name: Guy responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/ContactdbRecipientResponse201' '400': description: The request body is not valid json content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: Request body is not valid json '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required delete: operationId: DeleteRecipients summary: Delete Recipients tags: - Recipients description: '**This endpoint allows you to deletes one or more recipients.** The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete.' parameters: - $ref: '#/components/parameters/OnBehalfOf' requestBody: content: application/json: schema: type: array items: type: string example: - recipient_id1 - recipient_id2 responses: '200': description: '' content: application/json: schema: type: object '400': description: The request was formatted incorrectly or missing required parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: No recipient ids provided '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required get: operationId: ListRecipient summary: Retrieve recipients tags: - Recipients description: '**This endpoint allows you to retrieve all of your Marketing Campaigns recipients.** Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.' parameters: - name: page in: query description: Page index of first recipients to return (must be a positive integer) schema: type: integer - name: page_size in: query description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) schema: type: integer - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: title: List Recipients response type: object properties: recipients: type: array items: type: object required: - recipients '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 /v3/contactdb/recipients/{recipient_id}: parameters: - name: recipient_id in: path description: The ID of the recipient that you want to retrieve. required: true schema: type: string get: operationId: GetRecipient summary: Retrieve a single recipient tags: - Recipients description: '**This endpoint allows you to retrieve a single recipient by ID from your contact database.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ContactdbRecipient200' '400': description: Returned if `recipient_id` is not valid 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: A record for that recipient id does not exist content: application/json: schema: type: object delete: operationId: DeleteRecipient summary: Delete a Recipient tags: - Recipients description: '**This endpoint allows you to delete a single recipient with the given ID from your contact database.** > Use this to permanently delete your recipients from all of your contact lists and all segments if required by applicable law.' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '204': description: '' '400': description: Returned if `recipient_id` is not valid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: recipient not found '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required '404': description: A record for that recipient id does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: recipient_id is not valid /v3/contactdb/recipients/{recipient_id}/lists: parameters: - name: recipient_id in: path description: The ID of the recipient for whom you are retrieving lists. required: true schema: type: string get: operationId: GetRecipientList summary: Retrieve the lists that a recipient is on tags: - Recipients description: '**This endpoint allows you to retrieve the lists that a given recipient belongs to.** Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to.' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: type: object properties: lists: type: array items: $ref: '#/components/schemas/ContactdbList2xx' examples: response: value: lists: - id: 1234 name: Example list recipient_count: 42 '400': description: Returned if `recipient_id` is not valid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: recipient ID is invalid '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required '404': description: Returned if a record for the recipient id does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: recipient id not found /v3/contactdb/recipients/billable_count: get: operationId: GetBillable summary: Retrieve the count of billable recipients tags: - Recipients description: '**This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.** You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value.' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ContactdbRecipientCount200' examples: response: value: recipient_count: 1234 '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required /v3/contactdb/recipients/count: get: operationId: ListRecipientCount summary: Retrieve a Count of Recipients tags: - Recipients description: '**This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ContactdbRecipientCount200' examples: response: value: recipient_count: 1234 '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required /v3/contactdb/recipients/search: get: operationId: ListSearchRecipient summary: Search recipients tags: - Recipients description: '**This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.** field_name: * is a variable that is substituted for your actual custom field name from your recipient. * Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) * If field_name is a ''reserved'' date field, such as created_at or updated_at, the system will internally convert your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through Mon, 02 Feb 2015 23:59:59 GMT.' parameters: - name: '{field_name}' in: query schema: type: string - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: type: object properties: recipients: type: array items: $ref: '#/components/schemas/ContactdbRecipient200' 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: Fluffy type: text '400': description: The request was formatted incorrectly or missing required parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: 'The following parameters are not custom fields or reserved fields: [{field_name}]' - message: No search params are specified '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required post: operationId: SearchRecipient summary: Search recipients tags: - Recipients description: "Search using segment conditions without actually creating a segment.\n\ Body contains a JSON object with `conditions`, a list of conditions as described\ \ below, and an optional `list_id`, which is a valid list ID for a list to\ \ limit the search on.\n\nValid operators for create and update depend on\ \ the type of the field for which you are searching.\n\n- Dates:\n - `\"\ eq\"`, `\"ne\"`, `\"lt\"` (before), `\"gt\"` (after)\n - You may use MM/DD/YYYY\ \ for day granularity or an epoch for second granularity.\n - `\"empty\"\ `, `\"not_empty\"`\n - `\"is within\"`\n - You may use an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)\ \ date format or the # of days.\n- Text: `\"contains\"`, `\"eq\"` (is - matches\ \ the full field), `\"ne\"` (is not - matches any field where the entire field\ \ is not the condition value), `\"empty\"`, `\"not_empty\"`\n- Numbers: `\"\ eq\"`, `\"lt\"`, `\"gt\"`, `\"empty\"`, `\"not_empty\"`\n- Email Clicks and\ \ Opens: `\"eq\"` (opened), `\"ne\"` (not opened)\n\nField values must all\ \ be a string.\n\nSearch conditions using `\"eq\"` or `\"ne\"` for email clicks\ \ and opens should provide a \"field\" of either `clicks.campaign_identifier`\ \ or `opens.campaign_identifier`.\n\nThe condition value should be a string\ \ containing the id of a completed campaign.\n\nSearch conditions list may\ \ contain multiple conditions, joined by an `\"and\"` or `\"or\"` in the `\"\ and_or\"` field.\n\nThe first condition in the conditions list must have an\ \ empty `\"and_or\"`, and subsequent conditions must all specify an `\"and_or\"\ `." requestBody: content: application/json: schema: type: object properties: list_id: type: integer format: int32 conditions: type: array description: The conditions by which this segment should be created. items: $ref: '#/components/schemas/ContactdbSegmentsConditions' required: - list_id - conditions example: list_id: -27497588 conditions: - and_or: '' field: birthday value: 01/12/1985 operator: eq - and_or: '' field: birthday value: 01/12/1985 operator: eq - and_or: '' field: birthday value: 01/12/1985 operator: eq - and_or: '' field: birthday value: 01/12/1985 operator: eq responses: '200': description: '' content: application/json: schema: type: object properties: recipients: type: array items: type: object properties: created_at: type: integer email: type: string id: type: string last_emailed: type: integer last_clicked: type: integer last_opened: type: integer custom_fields: type: array items: type: object properties: id: type: integer name: type: string value: anyOf: - type: integer - type: string type: type: string updated_at: type: integer first_name: type: string recipient_count: type: integer examples: response: value: recipients: - created_at: -27901208 email: ut magna quis ipsum id: fugiat ad adipisicing ullamco last_emailed: 21626657 - created_at: 17466400 email: sunt irure id: et last_clicked: -23135244 last_opened: -44593357 first_name: est - created_at: -34495329 email: reprehenderit incididunt velit Lorem esse id: esse Ut ad dolore last_clicked: 10164083 last_opened: 34443062 - created_at: -37030673 email: amet deserunt fugiat voluptate id: et exercitation commodo id laborum last_clicked: -10497425 - created_at: 3658435 email: labore veniam id: ad pariatur esse last_opened: -84227501 custom_fields: - id: -5765608 name: proident pariatur value: do in magna mollit type: dolore ut - id: -31131201 name: laborum mollit value: 84434696 type: veniam updated_at: -56455352 first_name: Ut cupidatat nulla deserunt adipisicing last_clicked: -52862671 recipient_count: 65190677 '400': description: '' /v3/contactdb/reserved_fields: get: operationId: ListReservedField summary: Retrieve reserved fields tags: - Custom Fields description: '**This endpoint allows you to list all fields that are reserved and can''t be used for custom field names.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: type: object properties: reserved_fields: type: array items: type: object properties: name: type: string type: type: string examples: response: value: reserved_fields: - name: first_name type: text - name: last_name type: text - name: email type: text - name: created_at type: date - name: updated_at type: date - name: last_emailed type: date - name: last_clicked type: date - name: last_opened type: date - name: lists type: set - name: campaigns type: set - name: my_custom_field type: text '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - field: null message: authorization required /v3/contactdb/segments: post: operationId: CreateSegment summary: Create a Segment tags: - Segments description: "**This endpoint allows you to create a new segment.**\n\n\n Valid\ \ operators for create and update depend on the type of the field for which\ \ you are searching.\n\n**Dates**\n- \"eq\", \"ne\", \"lt\" (before), \"gt\"\ \ (after)\n - You may use MM/DD/YYYY for day granularity or an epoch for\ \ second granularity.\n- \"empty\", \"not_empty\"\n- \"is within\"\n -\ \ You may use an [ISO 8601 date format](https://en.wikipedia.org/wiki/ISO_8601)\ \ or the # of days.\n\n**Text**\n- \"contains\"\n- \"eq\" (is/equals - matches\ \ the full field)\n- \"ne\" (is not/not equals - matches any field where the\ \ entire field is not the condition value)\n- \"empty\"\n- \"not_empty\"\n\ \n**Numbers**\n- \"eq\" (is/equals)\n- \"lt\" (is less than)\n- \"gt\" (is\ \ greater than)\n- \"empty\"\n- \"not_empty\"\n\n**Email Clicks and Opens**\n\ - \"eq\" (opened)\n- \"ne\" (not opened)\n\nAll field values must be a string.\n\ \n\nConditions using \"eq\" or \"ne\" for email clicks and opens should provide\ \ a \"field\" of either `clicks.campaign_identifier` or `opens.campaign_identifier`.\n\ The condition value should be a string containing the id of a completed campaign.\n\ \n\nThe conditions list may contain multiple conditions, joined by an \"and\"\ \ or \"or\" in the \"and_or\" field.\n\nThe 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 /v3/contactdb/status: get: operationId: ListStatus summary: Get Recipient Upload Status tags: - Recipients description: '**This endpoint allows you to check the upload status of a Marketing Campaigns recipient.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: type: object properties: status: type: array items: type: object properties: id: type: string default: '' description: Valid values are "worker_delay" and "worker_delay_seconds" (the second value appears only if "worker_delay" has a value of "delayed"). value: type: string default: '' description: Valid values for the ID "worker_delay" are "OK" or "Delayed". Valid values for the ID "worker_delay_seconds" is the time of delay to upload. examples: response: value: status: - id: worker_delay value: delayed - id: worker_delay_seconds value: '75.0' /v3/contactdb/exports: post: operationId: ExportRecipient summary: Export Recipients tags: - Recipients description: '**Use this endpoint to export lists or segments of recipients**. If you would just like to have a link to the exported list sent to your email set the `notifications.email` option to `true` in the `POST` payload. If you would like to download the list, take the `id` that is returned and use the "Export Recipients Status" endpoint to get the `urls`. Once you have the list of URLs, make a `GET` request to each URL provided to download your CSV file(s). You specify the segments and or/recipient lists you wish to export by providing the relevant IDs in, respectively, the `segment_ids` and `list_ids` fields in the request body. The lists will be provided in either JSON or CSV files. To specify which of these you would required, set the request body `file_type` field to `json` or `csv`. You can also specify a maximum file size (in MB). If the export file is larger than this, it will be split into multiple files.' requestBody: content: application/json: schema: type: object properties: list_ids: description: IDs of the recipient lists you want to export. type: array items: type: integer segment_ids: description: IDs of the recipient segments you want to export. type: array items: type: integer notifications: type: object properties: email: type: boolean file_type: type: string description: File type for export file. Choose from `json` or `csv`. default: csv $ref: '#/components/schemas/FileType' max_file_size: description: The maximum size of an export file in MB. Note that when this option is specified, multiple output files may be returned from the export. default: 5000 type: integer responses: '202': description: '' content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' id: type: string description: The ID of the export job. required: - _metadata '400': description: '' content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/RecipientsError' '401': $ref: '#/components/responses/MarketingRecipients401' '403': $ref: '#/components/responses/MarketingRecipients403' '404': $ref: '#/components/responses/MarketingRecipients404' '500': $ref: '#/components/responses/MarketingRecipients500' get: operationId: ListExportRecipient summary: Get All Existing Exports tags: - Recipients description: "**Use this endpoint to retrieve details of all current exported\ \ jobs**.\n\nIt will return an array of objects, each of which records an\ \ export job in flight or recently completed. \n\nEach object's `export_type`\ \ field will tell you which kind of export it is and its `status` field will\ \ indicate what stage of processing it has reached. Exports which are `ready`\ \ will be accompanied by a `urls` field which lists the URLs of the export's\ \ downloadable files \u2014 there will be more than one if you specified a\ \ maximum file size in your initial export request.\n\nUse this endpoint if\ \ you have exports in flight but do not know their IDs, which are required\ \ for the \"Export Recipients Status\" endpoint." responses: '200': description: '' content: application/json: schema: type: object properties: result: type: array items: type: object properties: id: type: string description: Export jobs ID. status: type: string description: 'Allowed values: `pending`, `ready`, or `failure`.' created_at: type: string description: This ISO8601 timestamp when the export was created. completed_at: type: string description: This ISO8601 timestamp when the export was completed. expires_at: type: string description: This ISO8601 timestamp when the export expires. urls: type: array description: One or more download URLs for the recipient file(s) if the status is `ready`. items: type: string user_id: type: string description: User ID. export_type: type: string description: 'Allowed types: `contacts_export`, `list_export`, or `segment_export`.' segments: type: array items: type: object properties: ID: type: integer Name: type: string lists: type: array items: type: object properties: ID: type: integer Name: type: string _metadata: type: object properties: prev: type: string self: type: string next: type: string _metadata: type: object properties: prev: type: string self: type: string description: Link to this page. next: type: string description: Link to next page. '400': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string error_id: type: string required: - message '401': $ref: '#/components/responses/MarketingRecipients401' '403': $ref: '#/components/responses/MarketingRecipients403' '404': $ref: '#/components/responses/MarketingRecipients404' '500': $ref: '#/components/responses/MarketingRecipients500' /v3/contactdb/exports/{id}: parameters: - name: id in: path required: true schema: type: string get: operationId: GetExportRecipient summary: Export Recipients Status tags: - Recipients description: "**This endpoint can be used to check the status of a recipient\ \ export job**. \n\nTo use this call, you will need the `id` from the \"Export\ \ Recipients\" call.\n\nIf you would like to download a list, take the `id`\ \ that is returned from the \"Export Recipients\" endpoint and make an API\ \ request here to get the `urls`. Once you have the list of URLs, make a `GET`\ \ request on each URL to download your CSV file(s).\n\nTwilio SendGrid recommends\ \ exporting your recipients regularly as a backup to avoid issues or lost\ \ data." responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RecipientExport' '400': description: '' content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/RecipientsError' '401': $ref: '#/components/responses/MarketingRecipients401' '403': $ref: '#/components/responses/MarketingRecipients403' '404': $ref: '#/components/responses/MarketingRecipients404' '500': $ref: '#/components/responses/MarketingRecipients500' components: schemas: ContactdbCustomField: 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' example: name: first_name type: text ContactdbCustomFieldId2xx: title: ContactDB Custom field schema with ID. 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. ContactdbList2xx: title: ContactDB lists type: object properties: id: type: integer description: The reference ID of your list. name: type: string description: The name of your list. Must be unique against all other list and segment names. recipient_count: type: integer description: The count of recipients currently in the list. required: - id - name - recipient_count example: id: 1 name: listname recipient_count: 0 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 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 ContactdbRecipientResponse201: title: 'ContactDB: Recipient response' type: object properties: error_count: type: number default: 0 description: The number of errors found while adding recipients. error_indices: type: array default: [] description: 'The indices of the recipient(s) sent that caused the error. ' items: type: number new_count: type: number default: 0 description: The count of new recipients added to the contactdb. persisted_recipients: type: array default: [] description: The recipient IDs of the recipients that already existed from this request. items: type: string updated_count: type: number default: 0 description: The recipients who were updated from this request. errors: type: array items: type: object properties: message: type: string error_indices: type: array items: type: number required: - error_count - new_count - persisted_recipients - updated_count example: error_count: 1 error_indices: - 2 new_count: 2 persisted_recipients: - YUBh - bWlsbGVyQG1pbGxlci50ZXN0 updated_count: 0 errors: - message: Invalid email. error_indices: - 2 ContactdbRecipientCount200: title: 'ContactDB: Recipient Count' type: object properties: recipient_count: type: number description: The count of recipients. required: - recipient_count example: recipient_count: 1234 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 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 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 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 RecipientExport: title: recipient-export type: object properties: id: type: string status: type: string description: 'The export job''s status. Allowed values: `pending`, `ready`, or `failure`.' $ref: '#/components/schemas/Status' created_at: type: string description: The ISO8601 timestamp when the export was begun. updated_at: type: string description: The ISO8601 timestamp when the export was updated. completed_at: type: string description: The ISO8601 timestamp when the export was completed. expires_at: type: string description: The ISO8601 timestamp when the exported file on S3 will expire. urls: type: array description: One or more download URLs for the recipient file if the status is `ready`. items: type: string message: type: string description: A human readable message if the status is `failure`. _metadata: $ref: '#/components/schemas/Metadata' recipient_count: type: integer description: The total number of exported recipients. required: - id - status - created_at - updated_at - expires_at RecipientsError: title: error type: object properties: message: type: string field: type: string error_id: type: string parameter: type: string example: field: field_name message: error message required: - message Metadata: title: metadata type: object properties: prev: type: string format: uri description: The URL of the previous page of results. If this field isn't present, you're at the start of the list. self: type: string format: uri description: The URL of the current page of results. next: type: string format: uri description: The URL of the next page of results. If this field isn't present, you're at the end of the list. count: type: number description: The number of items in the entire list, i.e., across all pages. DeleteContacts: type: boolean enum: - true - false FileType: type: string enum: - csv - json Type: type: string enum: - date - text - number Operator: type: string enum: - eq - ne - lt - gt - contains AndOr: type: string enum: - and - or - '' Status: type: string enum: - pending - ready - failure responses: MarketingRecipients401: description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MarketingRecipients403: description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MarketingRecipients404: description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MarketingRecipients500: description: '' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: 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 `). When making a call on behalf of a Subuser, the property value should be the Subuser''s username (e.g., `on-behalf-of: `). 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 examples: {} 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: Custom Fields description: 'Twilio SendGrid Legacy Marketing Campaigns Contacts: Custom Fields API' - name: Lists description: 'Twilio SendGrid Legacy Marketing Campaigns Contacts: Lists API' - name: Recipients description: 'Twilio SendGrid Legacy Marketing Campaigns Contacts: Recipients API' - name: Segments description: 'Twilio SendGrid Legacy Marketing Campaigns Contacts: Segments API' externalDocs: description: Twilio SendGrid's official developer documentation. url: https://www.twilio.com/docs/sendgrid