SendGrid Sender Identities API

openapi: 3.2.0
info:
  title: Twilio SendGrid Legacy Marketing Campaigns Sender…
  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.


    See **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
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:
    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
  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