openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account IP Addresses 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: IP Addresses
  description: Twilio SendGrid IP Address API Operations
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:
                    - tim@sendgrid.net
                    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/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:
  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
  schemas:
    SortByDirection:
      type: string
      enum:
      - desc
      - asc
    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
  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