The Twilio SendGrid IP Address Management API combines functionality that was previously split between the Twilio SendGrid [IP Address API](https://docs.sendgrid.com/api-reference/ip-address) and [IP Pools API](https://docs.sendgrid.com/api-reference/ip-pools). This functionality includes adding IP addresses to your account, assigning IP addresses to IP Pools and Subusers, among other tasks.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid IP Address Management API
summary: The Twilio SendGrid IP Address Management API combines functionality that
was previously split between the Twilio SendGrid IP Address API and IP Pools API,
including adding IP addresses to your account, assigning IP addresses to IP Pools
and Subusers, among other tasks.
description: The Twilio SendGrid IP Address Management API combines functionality
that was previously split between the Twilio SendGrid [IP Address API](https://docs.sendgrid.com/api-reference/ip-address)
and [IP Pools API](https://docs.sendgrid.com/api-reference/ip-pools). This functionality
includes adding IP addresses to your account, assigning IP addresses to IP Pools
and Subusers, among other tasks.
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: ip_address_management
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/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 \u2264 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}:
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.
parameters:
- $ref: '#/components/parameters/IpAddressManagementPathIp'
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,
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/tsg_ip_address_management_v3.yaml