Twilio SendGrid IP Address API

openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid IP Address API
  summary: The Twilio SendGrid IP Address API allows you to add and manage dedicated
    IP addresses and IP Pools for your SendGrid account and Subusers.
  description: The Twilio SendGrid IP Address API allows you to add and manage dedicated
    IP addresses and IP Pools for your SendGrid account and Subusers. If you are sending
    any significant amount of email, SendGrid typically suggests sending from dedicated
    IPs. It's also best to send marketing and transactional emails from separate IP
    addresses. In order to do this, you'll need to set up IP Pools, which are groups
    of dedicated IP addresses you define to send particular types of messages. See
    the [**Dedicated IP Addresses**](https://docs.sendgrid.com/ui/account-and-settings/dedicated-ip-addresses)
    for more information about obtaining and allocating IPs.
  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: ips
servers:
- url: https://api.sendgrid.com
  description: for global users and subusers
- url: https://api.eu.sendgrid.com
  description: for EU regional subusers
paths:
  /v3/ips:
    post:
      operationId: AddIp
      summary: Add IPs
      tags:
      - IP Addresses
      description: '**This endpoint is for adding a(n) IP Address(es) to your account.**'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                count:
                  type: integer
                  description: The amount of IPs to add to the account.
                subusers:
                  type: array
                  description: Array of usernames to be assigned a send IP.
                  items:
                    type: string
                warmup:
                  type: boolean
                  default: false
                  description: Whether or not to warmup the IPs being added.
              required:
              - count
              example:
                count: 90323478
                subusers:
                - subuser1
                - subuser2
                warmup: true
                user_can_send: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  ips:
                    type: array
                    description: List of IP objects.
                    items:
                      type: object
                      properties:
                        ip:
                          type: string
                          description: IP added to account.
                        subusers:
                          type: array
                          description: Array of usernames assigned a send IP.
                          items:
                            type: string
                      required:
                      - ip
                      - subusers
                  remaining_ips:
                    type: integer
                    description: The number of IPs that can still be added to the
                      user.
                  warmup:
                    type: boolean
                    description: Whether or not the IPs are being warmed up.
                required:
                - ips
                - remaining_ips
                - warmup
              examples:
                response:
                  value:
                    ips:
                    - ip: 1.2.3.4
                      subusers:
                      - user
                      - subuser1
                    - ip: 1.2.3.5
                      subusers:
                      - user
                      - subuser1
                    remaining_ips: 1
                    warmup: true
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: one or more subusers do not belong to this user
    get:
      operationId: ListIp
      summary: Retrieve all IP addresses
      tags:
      - IP Addresses
      description: '**This endpoint allows you to retrieve a paginated list of all
        assigned and unassigned IPs.**


        Response includes warm up status, pools, assigned subusers, and reverse DNS
        info. The start_date field corresponds to when warmup started for that IP.


        A single IP address or a range of IP addresses may be dedicated to an account
        in order to send email for multiple domains. The reputation of this IP is
        determined by the aggregate performance of all email traffic sent from it.


        You can use the `limit` query parameter to set the page size. If your list
        contains more items than the page size permits, you can make multiple requests.
        Use the `offset` query parameter to control the position in the list from
        which to start retrieving additional items.'
      parameters:
      - name: ip
        in: query
        description: The IP address to get
        schema:
          type: string
      - name: exclude_whitelabels
        in: query
        description: Should we exclude reverse DNS records (whitelabels)?
        schema:
          type: boolean
      - name: limit
        in: query
        description: '`limit` sets the page size, i.e. maximum number of items from
          the list to be returned for a single API request. If omitted, the default
          page size is used.'
        schema:
          type: integer
          minimum: 1
          default: 10
      - $ref: '#/components/parameters/PaginationCommonOffset'
      - name: subuser
        in: query
        description: The subuser you are requesting for.
        schema:
          type: string
      - name: sort_by_direction
        in: query
        description: The direction to sort the results.
        schema:
          type: string
          $ref: '#/components/schemas/SortByDirection'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    ip:
                      type: string
                      description: An IP address.
                    subusers:
                      type: array
                      description: The subusers that are able to send email from this
                        IP.
                      items:
                        type: string
                    rdns:
                      type: string
                      description: The reverse DNS record for this IP address.
                    pools:
                      type: array
                      description: The IP pools that this IP has been added to.
                      items:
                        type: string
                    warmup:
                      type: boolean
                      description: Indicates if this IP address is currently warming
                        up.
                    start_date:
                      description: The date that the IP address was entered into warmup.
                      nullable: true
                      type: number
                    whitelabeled:
                      type: boolean
                      description: Indicates if this IP address is associated with
                        a reverse DNS record.
                    assigned_at:
                      description: The date that the IP address was assigned to the
                        user.
                      nullable: true
                      type: integer
                  required:
                  - ip
                  - subusers
                  - pools
                  - warmup
                  - start_date
                  - whitelabeled
                  - assigned_at
              examples:
                response:
                  value:
                  - ip: 192.168.1.1
                    pools:
                    - pool1
                    - pool2
                    whitelabeled: false
                    start_date: 1409616000
                    subusers:
                    - [email protected]
                    warmup: false
                    assigned_at: 1482883200
                  - ip: 208.115.214.22
                    pools: []
                    whitelabeled: true
                    rdns: o1.email.example.com
                    start_date: 1409616000
                    subusers: []
                    warmup: false
                    assigned_at: 1482883200
  /v3/ips/{ip_address}:
    parameters:
    - name: ip_address
      in: path
      description: The IP address you are retrieving the IP pools for.
      required: true
      schema:
        type: string
    get:
      operationId: GetIp
      summary: Retrieve all IP pools an IP address belongs to
      tags:
      - IP Addresses
      description: '**This endpoint allows you to see which IP pools a particular
        IP address has been added to.**


        The same IP address can be added to multiple IP pools.


        A single IP address or a range of IP addresses may be dedicated to an account
        in order to send email for multiple domains. The reputation of this IP is
        based on the aggregate performance of all the senders who use it.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  ip:
                    type: string
                    description: The IP address.
                  subusers:
                    type: array
                    description: The subusers that can send email using this IP address.
                    items:
                      type: string
                  rdns:
                    type: string
                    description: The reverse DNS record for this IP address.
                  pools:
                    type: array
                    description: The list of IP pools that this IP address belongs
                      to.
                    items:
                      type: string
                  warmup:
                    type: boolean
                    description: Indicates if this IP address is currently warming
                      up.
                  start_date:
                    description: The date that the IP address was entered into warmup.
                    nullable: true
                    type: integer
                  whitelabeled:
                    type: boolean
                    description: Indicates if this IP address is associated with a
                      reverse DNS record.
                required:
                - ip
                - subusers
                - rdns
                - pools
                - warmup
                - start_date
                - whitelabeled
              examples:
                response:
                  value:
                    ip: 000.00.00.0
                    subusers:
                    - subuser1
                    - subuser2
                    rdns: o1.em.example.com
                    pools:
                    - test1
                    warmup: false
                    start_date: null
                    whitelabeled: true
  /v3/ips/assigned:
    get:
      operationId: ListAssignedIp
      summary: Retrieve all assigned IPs
      tags:
      - IP Addresses
      description: '**This endpoint allows you to retrieve only assigned IP addresses.**


        A single IP address or a range of IP addresses may be dedicated to an account
        in order to send email for multiple domains. The reputation of this IP is
        based on the aggregate performance of all the senders who use it.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                title: List all assigned IPs response
                items:
                  type: object
                  properties:
                    ip:
                      type: string
                      description: The IP address.
                    pools:
                      type: array
                      description: The IP pools that this IP address has been added
                        to.
                      items:
                        type: string
                    warmup:
                      type: boolean
                      description: Indicates if this IP address is currently warming
                        up.
                    start_date:
                      type: integer
                      description: The start date that this IP address was entered
                        into warmup.
                  required:
                  - ip
                  - pools
                  - warmup
                  - start_date
              examples:
                response:
                  value:
                  - ip: 167.89.21.3
                    pools:
                    - new_test5
                    warmup: true
                    start_date: 1409616000
  /v3/ips/pools:
    post:
      operationId: CreateIpPool
      summary: Create an IP pool
      tags:
      - IP Pools
      description: "**This endpoint allows you to create an IP pool.**\n\nBefore you\
        \ can create an IP pool, you need to activate the IP in your SendGrid account:\
        \ \n\n1. Log into your SendGrid account.  \n1. Navigate to **Settings** and\
        \ then select **IP Addresses**.  \n1. Find the IP address you want to activate\
        \ and then click **Edit**.  \n1. Check **Allow my account to send mail using\
        \ this IP address**.\n1. Click **Save**."
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of your new IP pool.
                  maxLength: 64
              required:
              - name
              example:
                name: marketing
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpPools200'
              examples:
                response:
                  value:
                    name: marketing
    get:
      operationId: ListIpPool
      summary: Retrieve all IP pools
      tags:
      - IP Pools
      description: '**This endpoint allows you to get all of your IP pools.**'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IpPools200'
              examples:
                response:
                  value:
                  - name: marketing
                  - name: transactional
  /v3/ips/pools/{pool_name}:
    parameters:
    - name: pool_name
      in: path
      description: The name of the IP pool that you want to retrieve the IP addresses
        for.
      required: true
      schema:
        type: string
    get:
      operationId: GetIpPool
      summary: Retrieve all the IPs in a specified pool
      tags:
      - IP Pools
      description: '**This endpoint allows you to get all of the IP addresses that
        are in a specific IP pool.**'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  pool_name:
                    type: string
                    description: The name of the IP pool.
                    maxLength: 64
                  ips:
                    description: The IP addresses that belong to this pool.
                    type: array
                    items:
                      type: string
              examples:
                response:
                  value:
                    pool_name: Sample
                    ips:
                    - 192.168.1.1
                    - 192.158.1.2
                    - 192.138.2.1
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          description: The name of the error.
                        message:
                          type: string
                          description: A message explaining why the IP addresses could
                            not be listed.
              examples:
                response:
                  value:
                    errors:
                    - field: error
                      message: Unable to locate specified IPs Pool
    put:
      operationId: UpdateIpPool
      summary: Rename an IP pool
      tags:
      - IP Pools
      description: '**This endpoint allows you to update the name of an IP pool.**'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The new name for your IP pool.
                  maxLength: 64
              example:
                name: new_pool_name
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpPools200'
              examples:
                response:
                  value:
                    name: new_pool_name
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          nullable: true
                        message:
                          type: string
                          description: A message explaining why the name of your IP
                            pool could not be updated.
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: ip pool not found
    delete:
      operationId: DeleteIpPool
      summary: Delete an IP pool
      tags:
      - IP Pools
      description: '**This endpoint allows you to delete an IP pool.**'
      responses:
        '204':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: An error explaining why the pool could not be deleted.
              examples:
                response:
                  value:
                    error: Unable to locate specified IPs Pool
  /v3/ips/pools/{pool_name}/ips:
    parameters:
    - name: pool_name
      in: path
      description: The name of the IP pool you want to add the address to. If the
        name contains spaces, they must be URL encoded (e.g., "Test Pool" becomes
        "Test%20Pool").
      required: true
      schema:
        type: string
    post:
      operationId: AddIpToIpPool
      summary: Add an IP address to a pool
      tags:
      - IP Pools
      description: "**This endpoint allows you to add an IP address to an IP pool.**\n\
        \nYou can add the same IP address to multiple pools. It may take up to 60\
        \ seconds for your IP address to be added to a pool after your request is\
        \ made.\n\nBefore you can add an IP to a pool, you need to activate it in\
        \ your SendGrid account:\n\n1. Log into your SendGrid account.  \n1. Navigate\
        \ to **Settings** and then select **IP Addresses**.  \n1. Find the IP address\
        \ you want to activate and then click **Edit**.  \n1. Check **Allow my account\
        \ to send mail using this IP address**.\n1. Click **Save**.\n\nYou can retrieve\
        \ all of your available IP addresses from the \"Retrieve all IP addresses\"\
        \ endpoint."
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ip:
                  type: string
                  description: The IP address that you want to add to the named pool.
              example:
                ip: 0.0.0.0
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  ip:
                    type: string
                    description: The IP address.
                  pools:
                    type: array
                    description: The IP pools that this IP address has been added
                      to.
                    items:
                      type: string
                  start_date:
                    type: integer
                    description: A Unix timestamp indicating when the warmup process
                      began for the added IP address.
                  warmup:
                    type: boolean
                    description: Indicates if the IP address is in warmup.
                required:
                - ip
                - pools
                - start_date
                - warmup
              examples:
                response:
                  value:
                    ip: 000.00.00.0
                    pools:
                    - test1
                    start_date: 1409616000
                    warmup: true
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: The error returned.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          nullable: true
                        message:
                          type: string
                          description: A message explaining why the IP address could
                            not be added to the IP Pool.
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: resource not found
  /v3/ips/pools/{pool_name}/ips/{ip}:
    parameters:
    - name: pool_name
      in: path
      description: The name of the IP pool that you are removing the IP address from.
      required: true
      schema:
        type: string
    - name: ip
      in: path
      description: The IP address that you wish to remove.
      required: true
      schema:
        type: string
    delete:
      operationId: DeleteIpFromIpPool
      summary: Remove an IP address from a pool
      tags:
      - IP Pools
      description: '**This endpoint allows you to remove an IP address from an IP
        pool.**'
      responses:
        '204':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: An error explaining why the IP address could not
                      be removed from the IP pool.
              examples:
                response:
                  value:
                    error: Unable to locate specified IPs Pool
  /v3/ips/remaining:
    get:
      operationId: ListRemainingIpCount
      summary: Get remaining IPs count
      tags:
      - IP Addresses
      description: '**This endpoint gets amount of IP Addresses that can still be
        created during a given period and the price of those IPs.**'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        remaining:
                          type: integer
                          description: The number of IPs that can still be added to
                            the user.
                        period:
                          type: string
                          description: The length of time until user can add more
                            IPs.
                        price_per_ip:
                          type: number
                          description: The current cost to add an IP.
                      required:
                      - remaining
                      - period
                      - price_per_ip
                required:
                - results
              examples:
                response:
                  value:
                    results:
                    - remaining: 2
                      period: month
                      price_per_ip: 20
components:
  schemas:
    IpPools200:
      title: 'IP Pools: Pool Resp'
      type: object
      properties:
        name:
          type: string
          description: The name of the IP pool.
      example:
        name: sunt sint enim
    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
    SortByDirection:
      type: string
      enum:
      - desc
      - asc
  responses: {}
  parameters:
    PaginationCommonOffset:
      name: offset
      in: query
      required: false
      description: The number of items in the list to skip over before starting to
        retrieve the items for the requested page. The default `offset` of `0` represents
        the beginning of the list, i.e. the start of the first page. To request the
        second page of the list, set the `offset` to the page size as determined by
        `limit`. Use multiples of the page size as your `offset` to request further
        consecutive pages. E.g. assume your page size is set to `10`. An `offset`
        of `10` requests the second page, an `offset` of `20` requests the third page
        and so on, provided there are sufficiently many items in your list.
      schema:
        type: integer
        minimum: 0
        default: 0
  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: IP Addresses
  description: Twilio SendGrid IP Address API Operations
- name: IP Pools
  description: Twilio SendGrid IP Address Pool API Operations
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid