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 <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: <subuser-username>`). 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