{ "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.\n\n### Limitations\n\nThe `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": { "servers": [ { "url": "https://api.sendgrid.com", "description": "for global users" } ], "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": { "servers": [ { "url": "https://api.sendgrid.com", "description": "for global users" } ], "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": { "servers": [ { "url": "https://api.sendgrid.com", "description": "for global users" } ], "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).\n\nYou 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": { "servers": [ { "url": "https://api.sendgrid.com", "description": "for global users" } ], "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": { "servers": [ { "url": "https://api.sendgrid.com", "description": "for global users" } ], "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.\n\nA 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.\n\nEach 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.\n\nA 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" } }