{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Marketing Campaigns Senders API", "summary": "The Twilio SendGrid Marketing Campaigns Senders API allows you to create a verified sender from which your marketing emails will be sent.", "description": "The Twilio SendGrid Marketing Campaigns Senders API allows you to create a verified sender from which your marketing emails will be sent. To ensure our customers maintain the best possible sender reputations and to uphold legitimate sending behavior, we require customers to verify their Senders. A Sender represents your \u201cFrom\u201d email address\u2014the address your recipients will see as the sender of your emails.", "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_senders" } }, "servers": [ { "url": "https://api.sendgrid.com", "description": "The Twilio SendGrid v3 API" } ], "paths": { "/v3/marketing/senders": { "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "post": { "operationId": "CreateSender", "summary": "Create a Sender", "tags": [ "Senders" ], "description": "**This endpoint allows you to create a new Sender.**\n\n*You may create up to 100 unique Senders.*\n\nSenders are required to be verified before use. If your domain has been authenticated, a new Sender will auto verify on creation. Otherwise an email will be sent to the `from.email`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "nickname": { "type": "string", "description": "A nickname for the Sender. 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." } }, "required": [ "email", "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." } }, "required": [ "email" ] }, "address": { "type": "string", "description": "The physical address of the Sender." }, "address_2": { "type": "string", "description": "Additional Sender address information." }, "city": { "type": "string", "description": "The city of the Sender." }, "state": { "type": "string", "description": "The state of the Sender." }, "zip": { "type": "string", "description": "The zipcode of the Sender." }, "country": { "type": "string", "description": "The country of the Sender." } }, "required": [ "address", "city", "country", "from", "nickname", "reply_to" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sender" } } } }, "401": { "$ref": "#/components/responses/Senders401" }, "403": { "$ref": "#/components/responses/Senders403" }, "404": { "$ref": "#/components/responses/Senders404" }, "500": { "$ref": "#/components/responses/Senders500" } } }, "get": { "operationId": "ListSender", "summary": "Get a list of all Senders", "tags": [ "Senders" ], "description": "**This endpoint allows you to get a list of all your Senders.**", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "description": "An array of Sender objects.", "items": { "$ref": "#/components/schemas/Sender" } } } } } } }, "404": { "$ref": "#/components/responses/Senders404" } } } }, "/v3/marketing/senders/{id}": { "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" }, { "$ref": "#/components/parameters/SenderId" } ], "get": { "operationId": "GetSender", "summary": "Get a specific Sender", "tags": [ "Senders" ], "description": "**This endpoint allows you to get the details for a specific Sender by `id`.**", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sender" } } } }, "404": { "$ref": "#/components/responses/Senders404" } } }, "patch": { "operationId": "UpdateSender", "summary": "Update a Sender", "tags": [ "Senders" ], "description": "**This endpoint allows you to update an existing Sender.**\n\nUpdates to `from.email` require re-verification. If your domain has been authenticated, a new Sender will auto verify on creation. Otherwise, an email will be sent to the `from.email`.\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.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sender" } } } }, "400": { "$ref": "#/components/responses/Senders400" }, "403": { "$ref": "#/components/responses/Senders403" }, "404": { "$ref": "#/components/responses/Senders404" } } }, "delete": { "operationId": "DeleteSender", "summary": "Delete a Sender", "tags": [ "Senders" ], "description": "**This endpoint allows you to delete an existing Sender.**", "responses": { "204": { "description": "successfully deleted, no response in payload" }, "403": { "$ref": "#/components/responses/Senders403" }, "404": { "$ref": "#/components/responses/Senders404" } } } }, "/v3/marketing/senders/{id}/resend_verification": { "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" }, { "$ref": "#/components/parameters/SenderId" } ], "post": { "operationId": "ResetSenderVerification", "summary": "Resend a Sender verification", "tags": [ "Senders" ], "description": "**This endpoint allows you to resend the verification request for a specific Sender.**", "responses": { "204": { "description": "successfully posted, no response in payload" }, "400": { "$ref": "#/components/responses/Senders400" }, "404": { "$ref": "#/components/responses/Senders404" } } } } }, "components": { "schemas": { "Sender": { "title": "Sender", "example": { "id": 1, "nickname": "Example Orders", "from": { "email": "orders@example.com", "name": "Example Orders" }, "reply_to": { "email": "support@example.com", "name": "Example Support" }, "address": "1234 Fake St.", "address_2": "", "city": "San Francisco", "state": "CA", "zip": "94105", "country": "United States", "verified": true, "updated_at": 1449872165, "created_at": 1449872165, "locked": false }, "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of the Sender." }, "nickname": { "type": "string", "description": "A nickname for the Sender. 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." } }, "required": [ "email", "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." } }, "required": [ "email" ] }, "address": { "type": "string", "description": "The physical address of the Sender." }, "address_2": { "type": "string", "description": "Additional Sender address information." }, "city": { "type": "string", "description": "The city of the Sender." }, "state": { "type": "string", "description": "The state of the Sender." }, "zip": { "type": "string", "description": "The zipcode of the Sender." }, "country": { "type": "string", "description": "The country of the Sender." }, "verified": { "type": "boolean", "description": "A boolean flag indicating whether the Sender is verified or not. Only verified Senders can be used to send email." }, "locked": { "type": "boolean", "description": "A boolean flag that is `true` when the Sender is associated with a campaign in Draft, Scheduled, or In Progress status. You cannot update or delete a locked Sender." }, "updated_at": { "type": "integer", "description": "The time the Sender was last updated." }, "created_at": { "type": "integer", "description": "The time the Sender was created." } }, "required": [ "address", "city", "country", "created_at", "from", "id", "locked", "nickname", "reply_to", "updated_at", "verified" ] }, "SenderRequest": { "title": "Sender Request", "type": "object", "properties": { "nickname": { "type": "string", "description": "A nickname for the Sender. 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." }, "address_2": { "type": "string", "description": "Additional Sender address information." }, "city": { "type": "string", "description": "The city of the Sender." }, "state": { "type": "string", "description": "The state of the Sender." }, "zip": { "type": "string", "description": "The zipcode of the Sender." }, "country": { "type": "string", "description": "The country of the Sender." } }, "example": { "nickname": "Example Orders", "from": { "email": "orders@example.com", "name": "Example Orders" }, "reply_to": { "email": "support@example.com", "name": "Example Support" }, "address": "1234 Fake St.", "address_2": "", "city": "San Francisco", "state": "CA", "zip": "94105", "country": "United States" } }, "ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "An error message." }, "field": { "description": "When applicable, this property value will be the field that generated the error.", "nullable": true, "type": "string" }, "help": { "type": "object", "description": "When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error." } } } }, "id": { "type": "string", "description": "When applicable, this property value will be an error ID." } }, "example": { "errors": [ { "field": "field_name", "message": "error message" } ] } } }, "responses": { "Senders400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Senders401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Senders403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Senders404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Senders500": { "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" } }, "SenderId": { "name": "id", "in": "path", "description": "The unique identifier of the Sender.", "required": true, "schema": { "type": "integer" } } }, "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": "Senders", "description": "Twilio SendGrid Marketing Campaigns Senders API" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }