{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Legacy Marketing Campaigns Sender Identities API", "summary": "The Twilio SendGrid Legacy Marketing Campaigns Sender Identites API allows you to manage the email addresses used to send your marketing email. 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 Sender Identites API allows you to manage the email addresses used to send your marketing email. This API is operational, but we recommend using the current version of Marketing Campaigns to manage your [senders](https://docs.sendgrid.com/api-reference/senders/).\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_senders" } }, "servers": [ { "url": "https://api.sendgrid.com", "description": "The Twilio SendGrid v3 API" } ], "paths": { "/v3/senders": { "post": { "operationId": "CreateSender", "summary": "Create a Sender Identity", "tags": [ "Sender Identities" ], "description": "**This endpoint allows you to create a new sender identity.**\n\nYou may create up to 100 unique sender identities.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "nickname": "My Sender ID", "from": { "email": "from@example.com", "name": "Example INC" }, "reply_to": { "email": "replyto@example.com", "name": "Example INC" }, "address": "123 Elm St.", "address_2": "Apt. 456", "city": "Denver", "state": "Colorado", "zip": "80202", "country": "United States" }, "type": "object", "properties": { "nickname": { "type": "string", "description": "A nickname for the sender identity. Not used for sending." }, "from": { "type": "object", "required": [ "email" ] }, "reply_to": { "type": "object", "required": [ "email" ] }, "address": { "type": "string", "description": "The physical address of the sender identity." }, "address_2": { "type": "string", "description": "Additional sender identity address information." }, "city": { "type": "string", "description": "The city of the sender identity." }, "state": { "type": "string", "description": "The state of the sender identity." }, "zip": { "type": "string", "description": "The zipcode of the sender identity." }, "country": { "type": "string", "description": "The country of the sender identity." } }, "required": [ "address", "city", "country", "nickname" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderId" }, "examples": { "response": { "value": { "id": 1, "nickname": "My Sender ID", "from": { "email": "from@example.com", "name": "Example INC" }, "reply_to": { "email": "replyto@example.com", "name": "Example INC" }, "address": "123 Elm St.", "address_2": "Apt. 456", "city": "Denver", "state": "Colorado", "zip": "80202", "country": "United States", "verified": true, "updated_at": 1449872165, "created_at": 1449872165, "locked": false } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "The JSON you have submitted cannot be parsed.", "field": "" }, { "message": "You've reached your limit of 100 sender identities. Please delete one or more and try again.", "field": "" }, { "message": "nickname is required.", "field": "nickname" }, { "message": "You already have a sender identity with the same nickname.", "field": "nickname" }, { "message": "from_name is required.", "field": "from_name" }, { "message": "from_email is required.", "field": "from_email" }, { "message": "From email is not a valid email address.", "field": "from_email" }, { "message": "reply_to is required.", "field": "reply_to" }, { "message": "Reply to email is not a valid email address.", "field": "reply_to" }, { "message": "address is required.", "field": "address" }, { "message": "city is required.", "field": "city" }, { "message": "country is required.", "field": "country" } ] } } } } } } } }, "get": { "operationId": "ListSender", "summary": "Get all Sender Identities", "tags": [ "Sender Identities" ], "description": "**This endpoint allows you to retrieve a list of all sender identities that have been created for your account.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/SenderId" } } } }, "examples": { "response": { "value": { "result": [ { "id": 1, "nickname": "My Sender ID", "from": { "email": "from@example.com", "name": "Example INC" }, "reply_to": { "email": "replyto@example.com", "name": "Example INC" }, "address": "123 Elm St.", "address_2": "Apt. 456", "city": "Denver", "state": "Colorado", "zip": "80202", "country": "United States", "verified": true, "updated_at": 1449872165, "created_at": 1449872165, "locked": false } ] } } } } } } } } }, "/v3/senders/{sender_id}": { "parameters": [ { "name": "sender_id", "in": "path", "description": "The ID of the sender identity that you want to retrieve.", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "GetSender", "summary": "View a Sender Identity", "tags": [ "Sender Identities" ], "description": "**This endpoint allows you to retrieve a specific sender identity.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderId" }, "examples": { "response": { "value": { "id": 1, "nickname": "My Sender ID", "from": { "email": "from@example.com", "name": "Example INC" }, "reply_to": { "email": "replyto@example.com", "name": "Example INC" }, "address": "123 Elm St.", "address_2": "Apt. 456", "city": "Denver", "state": "Colorado", "zip": "80202", "country": "United States", "verified": true, "updated_at": 1449872165, "created_at": 1449872165, "locked": false } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "resource not found", "field": "id" } ] } } } } } } } }, "patch": { "operationId": "UpdateSender", "summary": "Update a Sender Identity", "tags": [ "Sender Identities" ], "description": "**This endpoint allows you to update a sender identity.**\n\nUpdates to `from.email` require re-verification.\n\nPartial updates are allowed, but fields that are marked as \"required\" in the POST (create) endpoint must not be nil if that field is included in the PATCH request.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderIdRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderId" }, "examples": { "response": { "value": { "id": 1, "nickname": "My Sender ID", "from": { "email": "from@example.com", "name": "Example INC" }, "reply_to": { "email": "replyto@example.com", "name": "Example INC" }, "address": "123 Elm St.", "address_2": "Apt. 456", "city": "Denver", "state": "Colorado", "zip": "80202", "country": "United States", "verified": true, "updated_at": 1449872165, "created_at": 1449872165, "locked": false } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "The JSON you have submitted cannot be parsed.", "field": "" }, { "message": "nickname is required.", "field": "nickname" }, { "message": "You already have a sender identity with the same nickname.", "field": "nickname" }, { "message": "from_name is required.", "field": "from_name" }, { "message": "from_email is required.", "field": "from_email" }, { "message": "From email is not a valid email address.", "field": "from_email" }, { "message": "reply_to is required.", "field": "reply_to" }, { "message": "Reply to email is not a valid email address.", "field": "reply_to" }, { "message": "address is required.", "field": "address" }, { "message": "city is required.", "field": "city" }, { "message": "country is required.", "field": "country" } ] } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "You may only update a sender identity when it is unlocked.", "field": "locked" } ] } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "resource not found", "field": "id" } ] } } } } } } } }, "delete": { "operationId": "DeleteSender", "summary": "Delete a Sender Identity", "tags": [ "Sender Identities" ], "description": "**This endpoint allows you to delete one of your sender identities.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "You may only delete a sender identity when it is unlocked.", "field": "locked" } ] } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "resource not found", "field": "id" } ] } } } } } } } } }, "/v3/senders/{sender_id}/resend_verification": { "parameters": [ { "name": "sender_id", "in": "path", "description": "The ID of the sender identity for which you would like to resend a verification email.", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "ResetSenderVerification", "summary": "Resend Sender Identity Verification", "tags": [ "Sender Identities" ], "description": "**This endpoint allows you to resend a sender identity verification email.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "" }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "The Sender Identity is already verified. No email sent.", "field": "" } ] } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "resource not found", "field": "id" } ] } } } } } } } } } }, "components": { "schemas": { "SenderIdRequest": { "title": "Sender ID Request", "type": "object", "properties": { "nickname": { "type": "string", "description": "A nickname for the sender identity. Not used for sending." }, "from": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address from which your recipient will receive emails." }, "name": { "type": "string", "description": "The name appended to the from email field. Typically your name or company name." } } }, "reply_to": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address to which your recipient will reply." }, "name": { "type": "string", "description": "The name appended to the reply to email field. Typically your name or company name." } } }, "address": { "type": "string", "description": "The physical address of the sender identity." }, "address_2": { "type": "string", "description": "Additional sender identity address information." }, "city": { "type": "string", "description": "The city of the sender identity." }, "state": { "type": "string", "description": "The state of the sender identity." }, "zip": { "type": "string", "description": "The zipcode of the sender identity." }, "country": { "type": "string", "description": "The country of the sender identity." } }, "example": { "nickname": "My Sender ID", "from": { "email": "from@example.com", "name": "Example INC" }, "reply_to": { "email": "replyto@example.com", "name": "Example INC" }, "address": "123 Elm St.", "address_2": "Apt. 456", "city": "Denver", "state": "Colorado", "zip": "80202", "country": "United States" } }, "SenderId": { "title": "Sender ID", "example": { "id": 1, "nickname": "My Sender ID", "from": { "email": "from@example.com", "name": "Example INC" }, "reply_to": { "email": "replyto@example.com", "name": "Example INC" }, "address": "123 Elm St.", "address_2": "Apt. 456", "city": "Denver", "state": "Colorado", "zip": "80202", "country": "United States", "verified": true, "updated_at": 1449872165, "created_at": 1449872165, "locked": false }, "type": "object", "properties": { "nickname": { "type": "string", "description": "A nickname for the sender identity. Not used for sending." }, "from": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address from which your recipient will receive emails." }, "name": { "type": "string", "description": "The name appended to the from email field. Typically your name or company name." } } }, "reply_to": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address to which your recipient will reply." }, "name": { "type": "string", "description": "The name appended to the reply to email field. Typically your name or company name." } } }, "address": { "type": "string", "description": "The physical address of the sender identity." }, "address_2": { "type": "string", "description": "Additional sender identity address information." }, "city": { "type": "string", "description": "The city of the sender identity." }, "state": { "type": "string", "description": "The state of the sender identity." }, "zip": { "type": "string", "description": "The zipcode of the sender identity." }, "country": { "type": "string", "description": "The country of the sender identity." }, "id": { "type": "integer", "description": "The unique identifier of the sender identity." }, "verified": { "type": "boolean", "description": "If the sender identity is verified or not. Only verified sender identities can be used to send email." }, "updated_at": { "type": "integer", "description": "The time the sender identity was last updated." }, "created_at": { "type": "integer", "description": "The time the sender identity was created." }, "locked": { "type": "boolean", "description": "True when the sender id is associated to a campaign in the Draft, Scheduled, or In Progress status. You cannot update or delete a locked sender identity." } }, "required": [ "address", "city", "country", "nickname" ] } }, "responses": {}, "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": {}, "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": "Sender Identities", "description": "Twilio SendGrid Legacy Marketing Campaigns Sender Identities API" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }