{ "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.\n\nSee [**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.**\n\n**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.**\n\nAdds 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.**\n\nYou 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.\n\nThe 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.**\n\nThe body of an API call to this endpoint must include an array of one or more recipient objects.\n\nIt 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.**\n\nThe 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.**\n\nBatch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of\nthe 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.**\n\n> 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.**\n\nEach 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.**\n\nYou 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.**\n\nfield_name:\n\n* is a variable that is substituted for your actual custom field name from your recipient.\n* Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200)\n* If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert\nyour epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to\nMon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through\nMon, 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.\nBody 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`.\nThe 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.**\n\nYou 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**.\n\nIf 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.\n\nIf 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).\n\nYou 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.\n\nThe 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`.\n\nYou 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" } }