openapi: 3.1.0 info: title: Twilio SendGrid Provisioning Account Sender Identities API summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid. You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).' 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: account_provisioning servers: - url: https://api.sendgrid.com description: for global users and subusers - url: https://api.eu.sendgrid.com description: for EU regional subusers security: - BearerAuth: [] tags: - name: Sender Identities description: Twilio SendGrid Legacy Marketing Campaigns Sender Identities 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.** You 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.** Updates to `from.email` require re-verification. Partial 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: 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 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 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 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. externalDocs: description: Twilio SendGrid's official developer documentation. url: https://www.twilio.com/docs/sendgrid