SendGrid IP Address Management API

openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account IP Address Management 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 Address Management
  description: Twilio SendGrid IP Address Management API
paths:
  /v3/send_ips/ips:
    get:
      summary: Get a List of all IP Addresses on your Account
      tags:
      - IP Address Management
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        ip:
                          type: string
                          description: An IP address on your account.
                        pools:
                          type: array
                          description: An array of IP Pools the IP address is assigned to.
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                description: The name of the IP Pool.
                              id:
                                type: string
                                description: The unique ID of the IP Pool.
                        is_auto_warmup:
                          type: boolean
                          description: Indicates if the IP address is set to automatically [warmup](https://docs.sendgrid.com/ui/sending-email/warming-up-an-ip-address).
                        is_parent_assigned:
                          type: boolean
                          nullable: true
                          description: Indicates if a parent on the account is able to send email from the IP address. This parameter will be returned only if the request was made by the parent account.
                        updated_at:
                          type: integer
                          nullable: true
                          description: A timestamp indicating when the IP was last updated.
                        is_enabled:
                          type: boolean
                          nullable: true
                          description: Indicates if the IP address is billed and able to send email. This parameter applies to non-Twilio SendGrid APIs that been added to your Twilio SendGrid account. This parameter's value is `null` for Twilio SendGrid IP addresses.
                        is_leased:
                          type: boolean
                          description: Indicates whether an IP address is leased from Twilio SendGrid. If `false`, the IP address is not a Twilio SendGrid IP; it is a customer's own IP that has been added to their Twilio SendGrid account.
                        added_at:
                          type: integer
                          description: A timestamp representing when the IP address was added to your account.
                        region:
                          type: string
                          description: The region to which the IP address is assigned. This property will only be returned if the `include_region` query parameter is included and set to `true` as part of the API request.
                          $ref: '#/components/schemas/Region'
                  _metadata:
                    type: object
                    properties:
                      next_params:
                        type: object
                        properties:
                          after_key:
                            type: string
                            nullable: true
                            description: Specifies which items to be returned by the API. When the `after_key` is specified, the API will return items beginning from the first item after the item specified. This parameter can be used in combination with `limit` to iterate through paginated results. The `after_key` cannot be used in combination with the `before_key` parameter.
                          before_key:
                            type: string
                            nullable: true
                            description: Specifies which items to be returned by the API. When the `before_key` is specified, the API will return items beginning from the first item before the item specified. This parameter can be used in combination with `limit` to iterate through paginated results. The `before_key` cannot be used in combination with the `after_key` parameter.
                          ip:
                            type: string
                            description: The IP address specified in the request with the `ip` query parameter. This parameter is returned only when an IP is included in the request.
                          is_leased:
                            type: boolean
                            description: Indicates whether an IP address is leased from Twilio SendGrid. If `false`, the IP address is not a Twilio SendGrid IP; it is a customer's own IP that has been added to their Twilio SendGrid account. This parameter is returned only if the IP address is leased.
                          is_enabled:
                            type: boolean
                            description: Indicates if the IP address is billed and able to send email. This parameter applies to non-Twilio SendGrid APIs that been added to your Twilio SendGrid account. This parameter's value is `null` for Twilio SendGrid IP addresses. This parameter is returned only if the IP address is enabled.
                          is_parent_assigned:
                            type: boolean
                            description: Indicates if a parent on the account is able to send email from the IP address. This parameter is returned only if the IP address is parent assigned.
                          pool:
                            type: string
                            description: The IP Pool ID specified in the request with the `pool` query parameter. This parameter is returned only when an IP Pool is included in the request.
                          start_added_at:
                            type: string
                            description: The beginning of the time window specified in the request with the `start_added_at` query parameter. This parameter is returned only when the `start_added_at` parameter is included in the request.
                          end_added_at:
                            type: string
                            description: The end of the time window specified in the request with the `end_added_at` query parameter. This parameter is returned only when the `end_added_at` parameter is included in the request.
                          limit:
                            type: string
                            description: The number of items returned in the request. This parameter is returned only when a `limit` is set using the `limit` query parameter in the request.
                          region:
                            type: string
                            description: The region to which the IP address is assigned. This property will only be returned if the `include_region` query parameter is included and set to `true` as part of the API request,
                            $ref: '#/components/schemas/Region1'
                          include_region:
                            type: string
                            description: Indicates whether or not to include the IP address's region. This property will only be returned if the `include_region` query parameter is included and set to `true` as part of the API request.
              examples:
                '200':
                  value:
                    result:
                    - ip: 127.0.0.1
                      pools:
                      - name: marketing_pool
                        id: '12345'
                      is_auto_warmup: true
                      is_parent_assigned: true
                      updated_at: null
                      is_enabled: true
                      is_leased: true
                      added_at: 1664390835
                      region: us
                    _metadata:
                      after_key: null
                      before_key: null
                      ip: 127.0.0.1
                      is_leased: true
                      is_enabled: true
                      is_parent_assigned: true
                      pool: marketing_pool
                      start_added_at: '1664390835'
                      end_added_at: '1664390835'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpAddressManagementErrorResponse'
              examples:
                limit length error:
                  value:
                    errors:
                    - field: limit
                      message: should be > 0 and ≤ 5000
                pool not found:
                  $ref: '#/components/examples/IpAddressManagement400PoolMissingError'
                pool type error:
                  $ref: '#/components/examples/IpAddressManagement400PoolTypeError'
                is_parent_assigned subuser error:
                  $ref: '#/components/examples/IpAddressManagement400IsParentAssignedSubuserError'
                is_parent_assigned value error:
                  $ref: '#/components/examples/IpAddressManagement400IsParentAssignedValueError'
                is_enabled value error:
                  $ref: '#/components/examples/IpAddressManagement400IsEnabledValueError'
                is_leased value error:
                  $ref: '#/components/examples/IpAddressManagement400IsLeasedValueError'
                start_added_at type error:
                  $ref: '#/components/examples/IpAddressManagement400StartAddedAtTypeError'
                end_added_at type error:
                  $ref: '#/components/examples/IpAddressManagement400EndAddedAtTypeError'
                pool parent_assigned:
                  $ref: '#/components/examples/IpAddressManagement400PoolIsParentAssignedError'
                after_key invalid ip:
                  $ref: '#/components/examples/IpAddressManagement400AfterKeyInvalidIpError'
                after_key and before_key included:
                  $ref: '#/components/examples/IpAddressManagement400AfterKeyBeforeKeyError'
                before_key invalid ip:
                  $ref: '#/components/examples/IpAddressManagement400BeforeKeyInvalidIpError'
        '401':
          $ref: '#/components/responses/IpAddressManagement401'
        '500':
          $ref: '#/components/responses/IpAddressManagement500'
      operationId: ListIp
      description: 'This operation returns a list of all IP addresses associated with your account. A sample of IP details is returned with each IP, including which Pools the IP is associated with, whether the IP is set to warm up automatically, and when the IP was last updated.


        ### Limitations


        The `is_parent_assigned` parameter and `pool` parameter cannot be used at the same time. By definition, an IP cannot be assigned to a Pool if it is not first enabled. You can use either the `before_key` or `after_key` in combination with the `limit` parameter to iterate through paginated results but not both.'
      parameters:
      - $ref: '#/components/parameters/IpAddressManagementQueryIp'
      - $ref: '#/components/parameters/IpAddressManagementLimit'
      - $ref: '#/components/parameters/IpAddressManagementAfterKey'
      - $ref: '#/components/parameters/IpAddressManagementBeforeKey'
      - $ref: '#/components/parameters/IpAddressManagementIsLeased'
      - $ref: '#/components/parameters/IpAddressManagementIsEnabled'
      - $ref: '#/components/parameters/IpAddressManagementIsParentAssigned'
      - $ref: '#/components/parameters/IpAddressManagementPool'
      - $ref: '#/components/parameters/IpAddressManagementStartAddedAt'
      - $ref: '#/components/parameters/IpAddressManagementEndAddedAt'
      - $ref: '#/components/parameters/IpAddressManagementRegion'
      - $ref: '#/components/parameters/IpAddressManagementIncludeRegion'
    post:
      summary: Add a Twilio SendGrid IP Address
      tags:
      - IP Address Management
      operationId: AddIp
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  ip:
                    type: string
                    description: The IP address that was added to your account.
                  is_auto_warmup:
                    type: boolean
                    description: Indicates if the IP address is set to automatically [warmup](https://docs.sendgrid.com/ui/sending-email/warming-up-an-ip-address).  This parameter is returned only if the IP address is set to automatically warm up.
                  is_parent_assigned:
                    type: boolean
                    description: Indicates if a parent on the account is able to send email from the IP address.
                  subusers:
                    type: array
                    description: An array of Subuser IDs the IP address was assigned to.
                    items:
                      type: string
                  region:
                    type: string
                    description: The region to which the IP address is assigned. This property will only be returned if the `include_region` query parameter is included and set to `true` as part of the API request.
                    $ref: '#/components/schemas/Region2'
              examples:
                '201':
                  value:
                    ip: 127.0.0.1
                    is_auto_warmup: true
                    is_parent_assigned: true
                    subusers:
                    - '12345'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpAddressManagementErrorResponse'
              examples:
                JSON parse error:
                  $ref: '#/components/examples/IpAddressManagement400JsonParseError'
                no ips remaining:
                  $ref: '#/components/examples/IpAddressManagement400IpNoRemainingError'
                is_auto_warmup not found:
                  $ref: '#/components/examples/IpAddressManagement400IsAutoWarmupMissingError'
                is_parent_assigned not found:
                  $ref: '#/components/examples/IpAddressManagement400IsParentAssignedMissingError'
                subusers unverified:
                  $ref: '#/components/examples/IpAddressManagement400SubusersUnverifiedError'
                subusers limit exceeded:
                  $ref: '#/components/examples/IpAddressManagement400SubusersLimitError'
                subusers caller id error:
                  $ref: '#/components/examples/IpAddressManagement400SubusersCallerIdError'
                subusers is_auto_warmup error:
                  $ref: '#/components/examples/IpAddressManagement400IsAutoWarmupSubusersError'
        '401':
          $ref: '#/components/responses/IpAddressManagement401'
        '500':
          $ref: '#/components/responses/IpAddressManagement500'
      description: This operation adds a Twilio SendGrid IP address to your account. You can also assign up to 100 Subusers to the IP address at creation.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                is_auto_warmup:
                  type: boolean
                  description: Indicates if the IP address is set to automatically [warmup](https://docs.sendgrid.com/ui/sending-email/warming-up-an-ip-address).
                is_parent_assigned:
                  type: boolean
                  description: Indicates if a parent on the account is able to send email from the IP address.
                subusers:
                  type: array
                  maxItems: 100
                  description: An array of Subuser IDs the IP address will be assigned to.
                  items:
                    type: string
                region:
                  type: string
                  default: us
                  description: The region to which the IP address is assigned. This property will only be returned if the `include_region` query parameter is included and set to `true` as part of the API request.
                  $ref: '#/components/schemas/Region3'
                include_region:
                  type: boolean
                  default: false
                  description: Boolean indicating whether or not to return the IP address's region information in the response.
              required:
              - is_auto_warmup
              - is_parent_assigned
            examples:
              example-1:
                value:
                  is_auto_warmup: true
                  is_parent_assigned: true
                  subusers:
                  - '12345'
  /v3/send_ips/ips/{ip}:
    parameters:
    - $ref: '#/components/parameters/IpAddressManagementPathIp'
    get:
      summary: Get Details for an IP Address
      tags:
      - IP Address Management
      parameters:
      - $ref: '#/components/parameters/IpAddressManagementIncludeRegion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ip:
                    type: string
                    description: The IP address specified in the request.
                  is_parent_assigned:
                    type: boolean
                    description: Indicates if a parent on the account is able to send email from the IP address.
                  is_auto_warmup:
                    type: boolean
                    description: Indicates if the IP address is set to automatically [warmup](https://docs.sendgrid.com/ui/sending-email/warming-up-an-ip-address).
                  pools:
                    type: array
                    description: An array of IP Pools the IP address is assigned to.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The ID of the IP Pool.
                        name:
                          type: string
                          description: The name of the IP Pool.
                  added_at:
                    type: integer
                    description: A timestamp indicating when the IP address was added to your account.
                  updated_at:
                    type: integer
                    nullable: true
                    description: A timestamp indicating when the IP was last updated.
                  is_enabled:
                    type: boolean
                    nullable: true
                    description: Indicates if the IP address is billed and able to send email. This parameter applies to non-Twilio SendGrid APIs that been added to your Twilio SendGrid account. This parameter's value is `null` for Twilio SendGrid IP addresses.
                  is_leased:
                    type: boolean
                    description: Indicates whether an IP address is leased from Twilio SendGrid. If `false`, the IP address is not a Twilio SendGrid IP; it is a customer's own IP that has been added to their Twilio SendGrid account.
                  region:
                    type: string
                    description: The region to which the IP address is assigned. This property will only be returned if the `include_region` query parameter is included and set to `true` as part of the API request. Possible values are `us` or `eu`.
              examples:
                '200':
                  value:
                    ip: 127.0.0.1
                    is_parent_assigned: true
                    is_auto_warmup: true
                    pools:
                    - id: '12345'
                      name: transactional_pool
                    added_at: 1664390835
                    updated_at: null
                    is_enabled: true
                    is_leased: true
                    region: us
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpAddressManagementErrorResponse'
              examples:
                ip invalid:
                  $ref: '#/components/examples/IpAddressManagement400IpInvalidError'
                ip not found:
                  $ref: '#/components/examples/IpAddressManagement400IpMissingError'
        '401':
          $ref: '#/components/responses/IpAddressManagement401'
        '500':
          $ref: '#/components/responses/IpAddressManagement500'
      operationId: GetIp
      description: This operation returns details for a specified IP address. Details include whether the IP is assigned to a parent account, set to warm up automatically, which Pools the IP is associated with, when the IP was added and modified, whether the IP is leased, and whether the IP is enabled. Note that this operation will not return Subuser information associated with the IP. To retrieve Subuser information, use the "Get a List of Subusers Assigned to an IP" endpoint.
    patch:
      summary: Update Details for an IP Address
      tags:
      - IP Address Management
      operationId: UpdateIp
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ip:
                    type: string
                    description: The IP address that was updated.
                  is_auto_warmup:
                    type: boolean
                    description: Indicates if the IP address is set to automatically [warmup](https://docs.sendgrid.com/ui/sending-email/warming-up-an-ip-address).
                  is_parent_assigned:
                    type: boolean
                    description: Indicates if a parent on the account is able to send email from the IP address. This parameter is returned only if the IP address is parent assigned.
                  is_enabled:
                    type: boolean
                    description: An array of Subuser IDs the IP address was assigned to. This parameter is returned only if the IP address is enabled.
              examples:
                '200':
                  value:
                    ip: 127.0.0.1
                    is_auto_warmup: true
                    is_parent_assigned: true
                    is_enabled: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpAddressManagementErrorResponse'
              examples:
                invalid ip address:
                  $ref: '#/components/examples/IpAddressManagement400IpInvalidError'
                ip unverified ownership:
                  $ref: '#/components/examples/IpAddressManagement400IpOwnershipError'
                JSON parse error:
                  $ref: '#/components/examples/IpAddressManagement400JsonParseError'
                missing required field:
                  $ref: '#/components/examples/IpAddressManagement400MissingRequiredFieldError'
        '401':
          $ref: '#/components/responses/IpAddressManagement401'
        '500':
          $ref: '#/components/responses/IpAddressManagement500'
      description: This operation updates an IP address's settings, including whether the IP is set to warm up automatically, if the IP is  assigned by a parent account, and whether the IP is enabled or disabled. The request body must include at least one of the `is_auto_warmup`, `is_parent_assigned`, or `is_enabled` fields.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                is_auto_warmup:
                  type: boolean
                  description: Indicates if the IP address is set to automatically [warmup](https://docs.sendgrid.com/ui/sending-email/warming-up-an-ip-address).
                is_parent_assigned:
                  type: boolean
                  description: Indicates if a parent on the account is able to send email from the IP address.
                is_enabled:
                  type: boolean
                  description: Indicates if the IP address is billed and able to send email. This parameter applies to non-Twilio SendGrid APIs that been added to your Twilio SendGrid account. This parameter's value is `null` for Twilio SendGrid IP addresses.
            examples:
              example-1:
                value:
                  is_auto_warmup: true
                  is_parent_assigned: true
                  is_enabled: true
  /v3/send_ips/ips/{ip}/subusers:
    parameters:
    - $ref: '#/components/parameters/IpAddressManagementPathIp'
    get:
      summary: Get a List of Subusers Assigned to an IP
      tags:
      - IP Address Management
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    description: An array of Subuser IDs that have been assigned the specified IP address.
                    items:
                      type: string
                  _metadata:
                    type: object
                    properties:
                      next_params:
                        type: object
                        description: A collection of fields that can be used to work the endpoint.
                        properties:
                          after_key:
                            type: string
                            nullable: true
                            description: Specifies which items to be returned by the API. When the `after_key` is specified, the API will return items beginning from the first item after the item specified. This parameter can be used in combination with `limit` to iterate through paginated results. The `after_key` cannot be used in combination with the `before_key` parameter.
                          limit:
                            type: string
                            description: The `limit` specified in the request. This parameter will be included only if it was specified in the request. This is not the default limit enforced by the API.
              examples:
                '200':
                  value:
                    result:
                    - '12345'
                    - '67890'
                    _metadata:
                      next_params:
                        after_key: null
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpAddressManagementErrorResponse'
              examples:
                invalid ip:
                  $ref: '#/components/examples/IpAddressManagement400InvalidIpError'
                limit value error:
                  $ref: '#/components/examples/IpAddressManagement400LimitValueError'
                after_key type error:
                  $ref: '#/components/examples/IpAddressManagement400AfterKeyTypeError'
        '401':
          $ref: '#/components/responses/IpAddressManagement401'
        '500':
          $ref: '#/components/responses/IpAddressManagement500'
      operationId: ListSubUserAssignedToIp
      description: 'This operation returns a list of Subuser IDs that have been assigned the specified IP address. To retrieve more information about the returned Subusers, use the [Subusers API](https://docs.sendgrid.com/api-reference/subusers-api/list-all-subusers).


        You can use the `after_key` and `limit` query parameters to iterate through paginated results. The maximum limit is 100, meaning you may retrieve up to 100 Subusers per request. If the `after_key` in the API response is not null, there are more Subusers assigned to the IP address than those returned in the request. You can repeat the request with the non-null `after_key` value and the same limit to retrieve the next group of Subusers.'
      parameters:
      - $ref: '#/components/parameters/IpAddressManagementAfterKey'
      - schema:
          type: integer
          maximum: 100
        in: query
        name: limit
        description: Specifies the number of results to be returned by the API. This parameter can be used in combination with the `after_key` parameters to iterate through paginated results. The maximum limit is 100.
  /v3/send_ips/ips/{ip}/subusers:batchAdd:
    parameters:
    - $ref: '#/components/parameters/IpAddressManagementPathIp'
    post:
      summary: Assign a Batch of Subusers to an IP
      tags:
      - IP Address Management
      operationId: AddSubUsersToIp
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ip:
                    type: string
                    description: The IP address the Subusers were assigned to.
                  subusers:
                    type: array
                    description: An array of Subuser IDs that were assigned to the specified IP address.
                    items:
                      type: string
              examples:
                example-1:
                  value:
                    ip: 127.0.0.1
                    subusers:
                    - '12345'
                    - '67890'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpAddressManagementErrorResponse'
              examples:
                invalid ip address:
                  $ref: '#/components/examples/IpAddressManagement400InvalidIpError'
                JSON parse error:
                  $ref: '#/components/examples/IpAddressManagement400JsonParseError'
                subusers empty:
                  $ref: '#/components/examples/IpAddressManagement400SubusersEmptyError'
                subuser caller id error:
                  $ref: '#/components/examples/IpAddressManagement400SubusersCallerIdError'
                subusers unverified:
                  $ref: '#/components/examples/IpAddressManagement400SubusersUnverifiedError'
                subusers limit exceeded:
                  $ref: '#/components/examples/IpAddressManagement400SubusersLimitError'
        '401':
          $ref: '#/components/responses/IpAddressManagement401'
        '500':
          $ref: '#/components/responses/IpAddressManagement500'
      description: This operation appends a batch of Subusers to a specified IP address. This endpoint 

# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/sendgrid-ip-address-management-api-openapi.yml