{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Marketing Campaigns Lists API", "summary": "The Twilio SendGrid Marketing Campaigns Lists API allows you to manage your contacts lists programmatically. Lists are static collections of Marketing Campaigns contacts.", "description": "The Twilio SendGrid Marketing Campaigns Lists API allows you to manage your contacts lists programmatically. Lists are static collections of Marketing Campaigns contacts. You can use this API to interact with the list objects themselves. To add contacts to a list, you must use the [Contacts API](https://docs.sendgrid.com/api-reference/contacts/).\n\nYou can also manage your lists using the Contacts menu in the [Marketing Campaigns application user interface](https://mc.sendgrid.com/contacts). For more information about lists and best practices for building them, see [**Building your Contact Lists**](https://sendgrid.com/docs/ui/managing-contacts/building-your-contact-list/).", "termsOfService": "https://www.twilio.com/legal/tos", "contact": { "name": "Twilio SendGrid Support", "url": "https://support.sendgrid.com/hc/en-us" }, "license": { "name": "MIT", "url": "https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE" }, "version": "1.0.0", "x-sendgrid": { "libraryPackage": "mc_lists" } }, "servers": [ { "url": "https://api.sendgrid.com", "description": "The Twilio SendGrid v3 API" } ], "paths": { "/v3/marketing/lists": { "post": { "operationId": "CreateMarketingList", "summary": "Create List", "tags": [ "Lists" ], "description": "**This endpoint creates a new contacts list.**\n\nOnce you create a list, you can use the UI to [trigger an automation](https://sendgrid.com/docs/ui/sending-email/getting-started-with-automation/#create-an-automation) every time you add a new contact to the list.\n\nA link to the newly created object is in `_metadata`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Your name for your list", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ], "example": { "name": "list-name" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" }, "examples": { "response": { "value": { "id": "ca7a3796-e8a8-4029-9ccb-df8937940562", "name": "list-name", "contact_count": 0, "_metadata": { "self": "https://api.sendgrid.com/v3/marketing/lists/ca7a3796-e8a8-4029-9ccb-df8937940562" } } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } } } } } } }, "get": { "operationId": "ListMarketingList", "summary": "Get All Lists", "tags": [ "Lists" ], "description": "**This endpoint returns an array of all of your contact lists.**", "parameters": [ { "name": "page_size", "in": "query", "description": "Maximum number of elements to return. Defaults to 100, returns 1000 max", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "page_token", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/List" } }, "_metadata": { "$ref": "#/components/schemas/Metadata" } } }, "examples": { "response": { "value": { "result": [ { "id": "abc12312-x3y4-1234-abcd-123qwe456rty", "name": "list-name", "contact_count": 0, "_metadata": { "self": "https://api.sendgrid.com/v3/marketing/lists/abc12312-x3y4-1234-abcd-123qwe456rty" } } ], "_metadata": { "self": "https://api.sendgrid.com/v3/marketing/lists?page_size=100&page_token=" } } } } } } } } } }, "/v3/marketing/lists/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the list on which you want to perform the operation.", "schema": { "type": "string" } } ], "get": { "operationId": "GetMarketingList", "summary": "Get a List by ID", "tags": [ "Lists" ], "description": "**This endpoint returns data about a specific list.**\nSetting the optional parameter `contact_sample=true` returns the `contact_sample` in the response body. Up to 50 of the most recent contacts uploaded or attached to a list will be returned.\nThe full contact count is also returned.", "parameters": [ { "name": "contact_sample", "in": "query", "description": "Setting this parameter to the true will cause the contact_sample to be returned", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The generated ID for your list.", "minLength": 36, "maxLength": 36 }, "name": { "type": "string", "description": "The name you gave your list." }, "contact_count": { "type": "integer", "description": "The number of contacts currently stored on the list." }, "_metadata": { "$ref": "#/components/schemas/SelfMetadata" }, "contact_sample": { "$ref": "#/components/schemas/ContactDetails" } } }, "examples": { "response": { "value": { "contact_count": 2, "contact_sample": { "id": "c3445f88-5c69-4237-86e6-9ec9de958050", "list_ids": [ "199abb98-0af3-4a8d-b371-6811ff85d062" ], "created_at": "2620-06-16T17:03:54.867Z", "updated_at": "4780-12-06T06:51:30.024Z" }, "_metadata": { "self": "https://api.sendgrid.com/v3/marketing/lists/199abb98-0af3-4a8d-b371-6811ff85d062" }, "id": "199abb98-0af3-4a8d-b371-6811ff85d062", "name": "list-name" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } } } } }, "patch": { "operationId": "UpdateMarketingList", "summary": "Update List", "tags": [ "Lists" ], "description": "**This endpoint updates the name of a list.**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Your name for your list." } }, "example": { "name": "updated-list-name" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" }, "examples": { "response": { "value": { "id": "abc12312-x3y4-1234-abcd-123qwe456rty", "name": "updated-list-name", "contact_count": 0, "_metadata": { "self": "https://api.sendgrid.com/v3/marketing/lists/abc12312-x3y4-1234-abcd-123qwe456rty" } } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "operationId": "DeleteMarketingList", "summary": "Delete a list", "tags": [ "Lists" ], "description": "**This endpoint allows you to deletes a specific list.**\n\nOptionally, you can also delete contacts associated to the list. The query parameter, `delete_contacts=true`, will delete the list and start an asynchronous job to delete associated contacts.", "parameters": [ { "name": "delete_contacts", "in": "query", "description": "Flag indicates that all contacts on the list are also to be deleted.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "The delete has been accepted and is processing.", "properties": { "job_id": { "type": "string", "description": "job_id of the async job" } } }, "examples": { "response": { "value": { "job_id": "abc12312-x3y4-1234-abcd-123qwe456rty" } } } } } }, "204": { "description": "", "content": { "application/json": { "schema": { "type": "string", "description": "The delete has been processed. " } } } }, "400": { "description": "The list could not be deleted. If it is still used by other resources, those resources are listed in the `resources` property of the error and must stop using the list before it can be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDeleteConflict" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } } }, "required": [ "errors" ] } } } } } } }, "/v3/marketing/lists/{id}/contacts": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the list on which you want to perform the operation.", "schema": { "type": "string" } } ], "delete": { "operationId": "DeleteContact", "summary": "Remove Contacts from a List", "tags": [ "Lists" ], "description": "**This endpoint allows you to remove contacts from a given list.**\n\nThe contacts will not be deleted. Only their list membership will be changed.", "parameters": [ { "name": "contact_ids", "in": "query", "description": "Comma separated list of contact IDs that you want to remove from the specified contacts list.", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "The removal is accepted and processing.", "properties": { "job_id": { "type": "string", "description": "job_id of the async job" } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "description": "The specified list ID does not exist or one or more contact IDs do not exist." } } } } } } }, "/v3/marketing/lists/{id}/contacts/count": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "ListContactCount", "summary": "Get List Contact Count", "tags": [ "Lists" ], "description": "**This endpoint returns the number of contacts on a specific list.**", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_count": { "type": "integer" }, "billable_count": { "type": "integer" } } }, "examples": { "response": { "value": { "contact_count": 0, "billable_count:": 0 } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "List": { "title": "list", "type": "object", "properties": { "id": { "type": "string", "description": "The generated ID for your list.", "minLength": 36, "maxLength": 36 }, "name": { "type": "string", "description": "The name you gave your list." }, "contact_count": { "type": "integer", "description": "The number of contacts currently stored on the list." }, "_metadata": { "$ref": "#/components/schemas/SelfMetadata" } } }, "InUseResource": { "title": "in_use_resource", "type": "object", "description": "A kind of resource that is using a list, and so is blocking its deletion.", "properties": { "type": { "type": "string", "description": "The kind of resource using the list. New values may be added over time, so clients should tolerate an unrecognized type.", "$ref": "#/components/schemas/Type" }, "ids": { "type": "array", "description": "The IDs of the resources of this type using the list.", "items": { "type": "string" } } }, "required": [ "type", "ids" ] }, "ListDeleteConflict": { "title": "list_delete_conflict", "type": "object", "description": "Returned when a list cannot be deleted. A single error is returned however many kinds of resource are using the list.", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "the field in the request that is incorrect" }, "message": { "type": "string", "description": "a description of what is specifically wrong" }, "resources": { "type": "array", "description": "When applicable, the resources currently using this list. The list cannot be deleted while they reference it. Absent when the request failed for any other reason.", "items": { "$ref": "#/components/schemas/InUseResource" } } }, "required": [ "field", "message" ] } } }, "required": [ "errors" ], "example": { "errors": [ { "field": "list_id", "message": "List cannot be deleted because it is used by other resources.", "resources": [ { "type": "automation", "ids": [ "05d032b4-350c-4b79-9e66-03ae1f844d90" ] }, { "type": "form", "ids": [ "817407ee-929f-11f1-88ab-5aa0a2f938db" ] } ] } ] } }, "Error": { "title": "error", "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" }, "error_id": { "type": "string" }, "parameter": { "type": "string" } }, "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." } } }, "ContactDetails": { "title": "contact-details2", "type": "object", "properties": { "id": { "type": "string", "minLength": 36, "maxLength": 36, "format": "uuid" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "unique_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone_number_id": { "type": "string" }, "external_id": { "type": "string" }, "anonymous_id": { "type": "string" }, "alternate_emails": { "items": { "type": "string", "format": "email" }, "nullable": true, "type": "array" }, "address_line_1": { "type": "string" }, "address_line_2": { "type": "string" }, "city": { "type": "string" }, "state_province_region": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" }, "phone_number": { "type": "string" }, "whatsapp": { "type": "string" }, "line": { "type": "string" }, "facebook": { "type": "string" }, "list_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "segment_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "custom_fields": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "_metadata": { "$ref": "#/components/schemas/SelfMetadata" } }, "required": [ "id", "list_ids", "created_at", "updated_at" ] }, "SelfMetadata": { "title": "selfMetadata", "type": "object", "properties": { "self": { "type": "string", "description": "A link to this object." } } }, "Type": { "type": "string", "enum": [ "automation", "form" ] } }, "responses": {}, "parameters": {}, "examples": {}, "requestBodies": {}, "headers": {}, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Twilio SendGrid requires you to authenticate with its APIs using an API key. The API key must be sent as a bearer token in the Authorization header." } } }, "tags": [ { "name": "Lists", "description": "Twilio SendGrid Marketing Campaigns Lists API" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }