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, 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 requires all Subuser assignments to succeed. If a Subuser assignment fails, this endpoint will return an error. requestBody: content: application/json: schema: type: object properties: subusers: type: array description: An array of Subuser IDs to be assigned to the specified IP address. All Subuser assignments must succeed. items: type: string required: - subusers examples: example-1: value: subusers: - '12345' - '67890' /v3/send_ips/ips/{ip}/subusers:batchDelete: parameters: - $ref: '#/components/parameters/IpAddressManagementPathIp' post: summary: Delete a Batch of Subusers from an IP tags: - IP Address Management operationId: DeleteSubUsersFromIp responses: '204': description: No Content '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' subusers limit exceeded: $ref: '#/components/examples/IpAddressManagement400SubusersLimitError' subusers caller id error: $ref: '#/components/examples/IpAddressManagement400SubusersCallerIdError' subusers unverified: $ref: '#/components/examples/IpAddressManagement400SubusersUnverifiedError' '401': $ref: '#/components/responses/IpAddressManagement401' '500': $ref: '#/components/responses/IpAddressManagement500' description: This operation removes a batch of Subusers from a specified IP address. requestBody: content: application/json: schema: type: object properties: subusers: type: array description: An array of Subuser IDs to be removed from the specified IP address. items: type: string required: - subusers examples: example-1: value: subusers: - '12345' - '67890' /v3/send_ips/pools: parameters: [] get: summary: GET all IP Pools that have Associated IPs tags: - IP Address Management operationId: ListIpPool description: 'This operation returns a list of your IP Pools and a sample of each Pools'' associated IP addresses. A maximum of 10 IPs will be returned per IP Pool by default. To retrieve additional IP addresses associated with a Pool, use the "Get IPs Assigned to an IP Pool" operation. Each user may have a maximum of 100 IP Pools.' parameters: - $ref: '#/components/parameters/IpAddressManagementLimit' - $ref: '#/components/parameters/IpAddressManagementAfterKey' - $ref: '#/components/parameters/IpAddressManagementQueryIp' - $ref: '#/components/parameters/IpAddressManagementRegion' - $ref: '#/components/parameters/IpAddressManagementIncludeRegion' responses: '200': description: OK content: application/json: schema: type: object properties: result: type: array 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. regions: type: array description: An array of the unique regions of all the IP addresses returned within the IP pool. items: type: string $ref: '#/components/schemas/Items' ips_preview: type: array maxItems: 10 description: A sample list of IP addresses associated with the IP Pool. The sample is limited to 10 results. items: type: string total_ip_count: type: integer description: The total number of IP addresses in the IP Pool. An IP Pool can have a maximum of 100 associated IP addresses. _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. ip: type: string description: The IP address specified in the request. This parameter will be returned only if it was specified in the request. 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. 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/Region4' 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: - name: transactional_pool id: '12345' ips_preview: - 127.0.0.1 - 127.0.0.2 total_ip_count: 2 - name: marketing_pool id: '67890' ips_preview: - 127.0.0.3 - 127.0.0.4 - 127.0.0.5 total_ip_count: 3 _metadata: next_params: after_key: null application/xml: schema: type: object properties: {} '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/IpAddressManagementErrorResponse' x-examples: example-1: errors: - field: after_key message: must be a numeric value examples: 400 limit error: $ref: '#/components/examples/IpAddressManagement400LimitValueError' 400 after_key type error: $ref: '#/components/examples/IpAddressManagement400AfterKeyTypeError' 400 after_key value error: $ref: '#/components/examples/IpAddressManagement400AfterKeyValueError' '401': $ref: '#/components/responses/IpAddressManagement401' '500': $ref: '#/components/responses/IpAddressManagement500' post: summary: Create an IP Pool with a Name and IP Assignments tags: - IP Address Management operationId: CreateIpPool responses: '201': description: Created content: application/json: schema: type: object properties: name: type: string description: The name assigned to the IP Pool. id: type: string description: The unique ID of the IP Pool. ips: type: array description: An array of IP addresses assigned to the IP Pool. All assignments must succeed. items: type: string examples: '201': value: name: transactional_pool id: '12345' ips: - 127.0.0.1 - 127.0.0.2 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/IpAddressManagementErrorResponse' examples: JSON parse error: $ref: '#/components/examples/IpAddressManagement400JsonParseError' name not found: $ref: '#/components/examples/IpAddressManagement400NameMissingError' name begins with dot or space: $ref: '#/components/examples/IpAddressManagement400NameDotSpaceError' name invalid length: $ref: '#/components/examples/IpAddressManagement400NameLengthError' name already exists: $ref: '#/components/examples/IpAddressManagement400NameExistsError' pool limit reached: $ref: '#/components/examples/IpAddressManagement400PoolLimitError' '401': $ref: '#/components/responses/IpAddressManagement401' '500': $ref: '#/components/responses/IpAddressManagement500' description: 'This operation will create a named IP Pool and associate specified IP addresses with the newly created Pool. This operation requires all IP assignments to succeed. If any IP assignments fail, this endpoint will return an error and the Pool will not be created. Each IP Pool may have a maximum of 100 assigned IP addresses.' requestBody: content: application/json: schema: type: object properties: name: type: string description: The name to assign to the IP Pool. An IP Pool name cannot begin with a space or period. ips: type: array description: An array of IP addresses to assign to the IP Pool. All assignments must succeed. maxItems: 100 items: type: string required: - name examples: example-1: value: name: transactional_pool ips: - 127.0.0.1 - 127.0.0.2 /v3/send_ips/pools/{poolid}: parameters: - $ref: '#/components/parameters/IpAddressManagementPoolId' get: summary: Get Details for an IP Pool tags: - IP Address Management operationId: GetIpPool parameters: - $ref: '#/components/parameters/IpAddressManagementIncludeRegion' responses: '200': description: OK content: application/json: schema: type: object properties: name: type: string description: The name of the IP Pool. id: type: string description: The unique ID of the IP Pool. ips_preview: type: array description: A sample list of IP addresses associated with the IP Pool. The sample is limited to 10 results. items: type: string total_ip_count: description: The total number of IP addresses in the IP Pool. An IP Pool can have a maximum of 100 associated IP addresses. type: integer ip_count_by_region: type: array description: The total number of IP addresses by region. this object is only returned if the `include_region` parameter is included and set to `true` in the API request. items: type: object properties: region: type: string description: The region associated with the number of IPs listed in the `count` property. $ref: '#/components/schemas/Region5' count: type: integer description: The number of IP addresses in the pool that are assigned to the region specified in the `region` property for this count. examples: '200': value: name: marketing_pool id: '12345' ips_preview: - 127.0.0.1 - 127.0.0.2 total_ip_count: 2 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/IpAddressManagementErrorResponse' examples: 400 poolid type error: $ref: '#/components/examples/IpAddressManagement400PoolIdTypeError' 400 poolid value error: $ref: '#/components/examples/IpAddressManagement400PoolIdValueError' '401': $ref: '#/components/responses/IpAddressManagement401' '500': $ref: '#/components/responses/IpAddressManagement500' description: 'This operation will return the details for a specified IP Pool, including the Pool''s name, ID, a sample list of the IPs associated with the Pool, and the total number of IPs belonging to the Pool. A maximum of 10 IPs will be returned per IP Pool by default. To retrieve additional IP addresses associated with a Pool, use the "Get IPs Assigned to an IP Pool" operation.' put: summary: Update an IP Pool Name tags: - IP Address Management operationId: UpdateIpPool responses: '200': description: OK content: application/json: schema: type: object properties: name: type: string description: The name assigned to the IP Pool. id: type: string description: The unique ID of the IP Pool. examples: '200': value: name: marketing_pool id: '12345' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/IpAddressManagementErrorResponse' examples: JSON parse error: $ref: '#/components/examples/IpAddressManagement400JsonParseError' name not found: $ref: '#/components/examples/IpAddressManagement400NameMissingError' name begins with dot or space: $ref: '#/components/examples/IpAddressManagement400NameDotSpaceError' name invalid length: $ref: '#/components/examples/IpAddressManagement400NameLengthError' poolid type error: $ref: '#/components/examples/IpAddressManagement400PoolIdTypeError' poolid not found: $ref: '#/components/examples/IpAddressManagement400PoolIdMissingError' name already exists: $ref: '#/components/examples/IpAddressManagement400NameExistsError' '401': $ref: '#/components/responses/IpAddressManagement401' '500': $ref: '#/components/responses/IpAddressManagement500' description: This operation will rename an IP Pool. An IP Pool name cannot start with a dot/period (.) or space. requestBody: content: application/json: schema: type: object properties: name: type: string description: The name to assign to the IP Pool. An IP Pool name cannot begin with a space or period. required: - name examples: example-1: value: name: marketing_pool delete: summary: Delete IP Pool tags: - IP Address Management operationId: DeleteIpPool responses: '204': description: No Content '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/IpAddressManagementErrorResponse' examples: poolid type error: $ref: '#/components/examples/IpAddressManagement400PoolIdTypeError' poolid not found: $ref: '#/components/examples/IpAddressManagement400PoolIdMissingError' '401': $ref: '#/components/responses/IpAddressManagement401' '500': $ref: '#/components/responses/IpAddressManagement500' description: This operation deletes an IP Pool and unassigns all IP addresses associated with the Pool. IP addresses associated with the deleted Pool will remain in your account. /v3/send_ips/pools/{poolid}/ips: get: summary: Get IPs Assigned to an IP Pool 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 assigned to the IP Pool. 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/Region6' pools: type: array description: IP Pools the IP address is assigned to. items: type: object properties: id: type: string description: The unique ID of the IP Pool. name: type: string description: The name of the IP Pool. _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. 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: - id: '12345' name: transactional_pool _metadata: next_params: after_key: null '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/IpAddressManagementErrorResponse' examples: 400 poolid type error: $ref: '#/components/examples/IpAddressManagement400PoolIdTypeError' 400 poolid value error: $ref: '#/components/examples/IpAddressManagement400PoolIdValueError' 400 limit value error: $ref: '#/components/examples/IpAddressManagement400LimitValueError' '401': $ref: '#/components/responses/IpAddressManagement401' '500': $ref: '#/components/responses/IpAddressManagement500' operationId: ListIpAssignedToIpPool description: This operation returns the IP addresses that are assigned to the specified IP pool. parameters: - $ref: '#/components/parameters/IpAddressManagementLimit' - $ref: '#/components/parameters/IpAddressManagementAfterKey' - $ref: '#/components/parameters/IpAddressManagementIncludeRegion' parameters: - $ref: '#/components/parameters/IpAddressManagementPoolId' /v3/send_ips/pools/{poolid}/ips:batchAdd: parameters: - $ref: '#/components/parameters/IpAddressManagementPoolId' post: summary: Add a Batch of IPs to an IP Pool tags: - IP Address Management operationId: AddIpsToIpPool responses: '200': description: OK content: application/json: schema: type: object properties: name: type: string description: The name of the IP Pool. id: type: string description: The unique ID of the IP Pool. ips: type: array description: An array of IP addresses assigned to the IP Pool. items: type: string examples: '200': value: name: marketing_pool id: '12345' ips: - 127.0.0.1 - 127.0.0.2 - 127.0.0.3 - 127.0.0.4 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/IpAddressManagementErrorResponse' examples: poolid type error: $ref: '#/components/examples/IpAddressManagement400PoolIdTypeError' poolid not found: $ref: '#/components/examples/IpAddressManagement400PoolIdMissingError' ips not found: $ref: '#/components/examples/IpAddressManagement400IpsMissingError' ips invalid length: $ref: '#/components/examples/IpAddressManagement400IpsLengthError' ips unassigned: $ref: '#/components/examples/IpAddressManagement400IpsAssignmentError' ips limit exceeded: $ref: '#/components/examples/IpAddressManagement400IpsLimitError' '401': $ref: '#/components/responses/IpAddressManagement401' '500': $ref: '#/components/responses/IpAddressManagement500' description: This operation appends a batch of IPs to an IP Pool. This operation requires all IP assignments to succeed. If any IP assignments fail, this endpoint will return an error. requestBody: content: application/json: schema: type: object properties: ips: type: array description: An array of IP addresses to assign to the specified IP Pool. All assignments must succeed. items: type: string required: - ips examples: example-1: value: ips: - 127.0.0.1 - 127.0.0.2 - 127.0.0.3 - 127.0.0.4 /v3/send_ips/pools/{poolid}/ips:batchDelete: parameters: - $ref: '#/components/parameters/IpAddressManagementPoolId' post: summary: Delete a Batch of IPs from an IP Pool tags: - IP Address Management operationId: DeleteIpsFromIpPool responses: '204': description: No Content '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/IpAddressManagementErrorResponse' examples: poolid type error: $ref: '#/components/examples/IpAddressManagement400PoolIdTypeError' poolid not found: $ref: '#/components/examples/IpAddressManagement400PoolIdMissingError' ips not found: value: errors: - field: string message: string JSON parse error: $ref: '#/components/examples/IpAddressManagement400JsonParseError' ips invalid length: $ref: '#/components/examples/IpAddressManagement400IpsLengthError' ips not found in pool: $ref: '#/components/examples/IpAddressManagement400IpsIpNotInPoolError' '401': $ref: '#/components/responses/IpAddressManagement401' '500': $ref: '#/components/responses/IpAddressManagement500' description: This operation removes a batch of IPs from an IP Pool. All IPs associated with the Pool will be unassigned from the deleted Pool. However, this operation does not remove the IPs from your account. requestBody: content: application/json: schema: type: object properties: ips: type: array description: An array of IP addresses to remove from the specified IP Pool. items: type: string required: - ips examples: example-1: value: ips: - 127.0.0.1 - 127.0.0.2 - 127.0.0.3 - 127.0.0.4 components: schemas: IpAddressManagementErrorResponse: type: object example-1: errors: - field: after_key message: must be a numeric value description: IP Address Management Error Response Schema properties: errors: type: array description: An array of error objects. items: type: object properties: field: type: string description: Indicates which field caused the error. This may be an empty string if no specific field is responsible for the error. message: type: string description: An error-specific message that provides more information about the error's cause. Region: type: string enum: - eu - us Region1: type: string enum: - all - us - eu Region2: type: string enum: - eu - us Region3: type: string enum: - eu - us Items: type: string enum: - eu - us Region4: type: string enum: - all - us - eu Region5: type: string enum: - us - eu Region6: type: string enum: - eu - us Region7: type: string enum: - all - eu - us responses: IpAddressManagement401: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/IpAddressManagementErrorResponse' x-examples: example-1: errors: - field: '' message: 'missing required scope: scope1, scope2' examples: Missing required scope: value: errors: - field: '' message: 'missing required scope: scope1, scope2' application/xml: schema: type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string x-examples: example-1: errors: - field: '' message: 'missing required scope: scope1, scope2' IpAddressManagement500: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/IpAddressManagementErrorResponse' x-examples: example-1: errors: - field: '' message: internal server error examples: Generic 500: value: errors: - field: '' message: internal server error parameters: IpAddressManagementPoolId: name: poolid in: path required: true schema: type: string description: Specifies the unique ID for an IP Pool. IpAddressManagementPathIp: name: ip in: path schema: type: string description: The `ip` path parameter specifies an IP address to make the request against. required: true IpAddressManagementLimit: name: limit in: query required: false schema: type: integer description: Specifies the number of results to be returned by the API. This parameter can be used in combination with the `before_key` or `after_key` parameters to iterate through paginated results. IpAddressManagementAfterKey: name: after_key in: query required: false schema: type: integer 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. IpAddressManagementQueryIp: name: ip in: query required: false schema: type: string description: Specifies an IP address. The `ip` query parameter can be used to filter results by IP address. IpAddressManagementBeforeKey: name: before_key in: query required: false schema: type: string 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. IpAddressManagementIsLeased: name: is_leased in: query required: false schema: 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. IpAddressManagementIsEnabled: name: is_enabled in: query required: false schema: 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. IpAddressManagementIsParentAssigned: name: is_parent_assigned in: query required: false schema: type: boolean description: A parent must be assigned to an IP address before the parent can send mail from the IP and before the address can be assigned to an IP pool. Set this parameter value to true to allow the parent to send mail from the IP and make the IP eligible for IP pool assignment using the IP pool endpoints. IpAddressManagementPool: name: pool in: query required: false schema: type: string description: Specifies the unique ID for an IP Pool. When included, only IP addresses belonging to the specified Pool will be returned. IpAddressManagementStartAddedAt: name: start_added_at in: query required: false schema: type: integer description: The `start_added_at` and `end_added_at` parameters are used to set a time window. IP addresses that were added to your account in the specified time window will be returned. The `start_added_at` parameter sets the beginning of the time window. IpAddressManagementEndAddedAt: name: end_added_at in: query required: false schema: type: integer description: The `start_added_at` and `end_added_at` parameters are used to set a time window. IP addresses that were added to your account in the specified time window will be returned. The `end_added_at` parameter sets the end of the time window. IpAddressManagementRegion: name: region in: query required: false description: Allowed values are `all`, `eu`, and `us`. If you provide a specific region, results will include all pools that have at least one IP in the filtered region. If `all`, pools with at least one IP (regardless of region) will be returned. If the `region` filter is not provided, the query returns all pools, including empty ones. schema: type: string $ref: '#/components/schemas/Region7' IpAddressManagementIncludeRegion: name: include_region in: query required: false description: Boolean indicating whether or not to return the IP Pool's region information in the response. schema: type: boolean default: false examples: IpAddressManagement400PoolIdTypeError: value: errors: - field: poolid message: must be a numeric value IpAddressManagement400PoolIdValueError: value: errors: - field: poolid message: not found IpAddressManagement400LimitValueError: value: errors: - field: limit message: should be > 0 and <= 100 IpAddressManagement400AfterKeyTypeError: value: errors: - field: after_key message: must be a numeric value IpAddressManagement400AfterKeyValueError: value: errors: - field: after_key message: must be >= 0 IpAddressManagement400JsonParseError: value: errors: - field: '' message: failed to parse the request body as a JSON payload IpAddressManagement400NameMissingError: value: errors: - field: name message: not found in the request body IpAddressManagement400NameDotSpaceError: value: errors: - field: name message: cannot start with a dot or a space IpAddressManagement400NameLengthError: value: errors: - field: name message: needs to be between 2 to 64 characters long IpAddressManagement400NameExistsError: value: errors: - field: name message: already exists IpAddressManagement400PoolLimitError: value: errors: - field: '' message: 100 pools limit has been reached IpAddressManagement400PoolIdMissingError: value: errors: - field: poolid message: not found IpAddressManagement400IpsLimitError: value: errors: - field: ips message: "the total number of IPs per pool cannot exceed 100. current IP\ \ count in \u2018pool\u2019 is \u201898\u2019" IpAddressManagement400IpsAssignmentError: value: errors: - field: ips message: 'unable to verify IPs assignability: 127.0.0.1, 127.0.0.2' IpAddressManagement400IpsLengthError: value: errors: - field: ips message: the number of IPs must be between 1 and 100 IpAddressManagement400IpsMissingError: value: errors: - field: ips message: not found in the request body IpAddressManagement400IpsIpNotInPoolError: value: errors: - field: ips message: "not found in pool \u2018marketing_pool\u2019: 127.0.0.1, 127.0.0.2" IpAddressManagement400InvalidIpError: value: errors: - field: '' message: invalid IP address IpAddressManagement400SubusersEmptyError: value: errors: - field: subusers message: must not be empty IpAddressManagement400SubusersLimitError: value: errors: - field: subusers message: cannot assign more than 1000 subusers per call IpAddressManagement400SubusersCallerIdError: value: errors: - field: subusers message: "cannot contain caller\u2019s userID" IpAddressManagement400SubusersUnverifiedError: value: errors: - field: subusers message: 'unverified subusers: 123, 456, 789' IpAddressManagement400PoolMissingError: value: errors: - field: pool message: not found IpAddressManagement400PoolTypeError: value: errors: - field: pool message: must be numeric IpAddressManagement400IsParentAssignedSubuserError: value: errors: - field: is_parent_assigned message: cannot be used for a sub user account IpAddressManagement400IsParentAssignedValueError: value: errors: - field: is_parent_assigned message: 'must be one of the following: true, false' IpAddressManagement400IsEnabledValueError: value: errors: - field: is_enabled message: 'must be one of the following: true, false' IpAddressManagement400IsLeasedValueError: value: errors: - field: is_leased message: 'must be one of the following: true, false' IpAddressManagement400StartAddedAtTypeError: value: errors: - field: start_added_at message: must be numeric IpAddressManagement400EndAddedAtTypeError: value: errors: - field: end_added_at message: must be numeric IpAddressManagement400PoolIsParentAssignedError: value: errors: - field: pool message: "cannot be used with \u2018is_parent_assigned\u2019" IpAddressManagement400AfterKeyInvalidIpError: value: errors: - field: after_key message: invalid IP address IpAddressManagement400BeforeKeyInvalidIpError: value: errors: - field: before_key message: invalid IP address IpAddressManagement400AfterKeyBeforeKeyError: value: errors: - field: after_key message: "cannot be used with \u2018before_key\u2019" IpAddressManagement400IpMissingError: value: errors: - field: ip message: not found IpAddressManagement400IpInvalidError: value: errors: - field: ip message: invalid IP address IpAddressManagement400IpNoRemainingError: value: errors: - field: '' message: No IPs remaining IpAddressManagement400IsAutoWarmupMissingError: value: errors: - field: is_auto_warmup message: not found in the request body IpAddressManagement400IsParentAssignedMissingError: value: errors: - field: is_parent_assigned message: not found in the request body IpAddressManagement400IsAutoWarmupSubusersError: value: errors: - field: subusers message: 'these users must have at least one IP that is not in warmup: 123, 456' IpAddressManagement400IpOwnershipError: value: errors: - field: ip message: unable to verify IP ownership IpAddressManagement400MissingRequiredFieldError: value: errors: - field: '' message: 'at least one of the following is required: is_enabled, is_auto_warmup, is_parent_assigned' 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 Address Management description: Twilio SendGrid IP Address Management API externalDocs: description: Twilio SendGrid's official developer documentation. url: https://www.twilio.com/docs/sendgrid