openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Senders 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: Senders
  description: Twilio SendGrid Marketing Campaigns Senders 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.**


        *You may create up to 100 unique Senders.*


        Senders 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.**


        Updates 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`.


        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.'
      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:
  responses:
    Senders404:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Senders403:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Senders400:
      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
    Senders401:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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
    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
  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
    SenderId:
      name: id
      in: path
      description: The unique identifier of the Sender.
      required: true
      schema:
        type: integer
  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