# IPs The IP API endpoint allows you to access information regarding the IPs allocated to your Mailgun account that are used for outbound sending. ## Remove an IP from the domain pool, unlink a DIPP or remove the domain pool - [DELETE /v3/domains/{name}/ips/{ip}](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ip-pools/delete-v3-domains--name--ips--ip-.md): The behavior of the endpoint depends on the value of the ip parameter. It can be one of the following: * a valid IP address: this IP address will be removed from the domain pool. * string all: the entire domain pool will be removed. As far as the system is concerned, such domain will no longer exist. * string ip_pool: the DIPP which is currently linked to the domain will be unlinked. ### Removing An IP Note that it's impossible to alter domain IPs if a DIPP is linked to the domain. If the account is not eligible for shared IPs, additional rules apply: * removing the last IP from the domain is not allowed; * if all of the remaining dedicated IPs are on warmup, an extra IP might be added to the domain pool. ### Unlinking The DIPP The account must have 'DIPPs' feature enabled. Either ip or pool_id query parameter must be specified, but not both. If the special value shared is used for the replacement IP, the account must be eligible for shared IPs. In this case the system will assign a shared IP as the replacement. ## Remove an IP from the domain pool, unlink a DIPP or remove the domain pool - [DELETE /v3/domains/{name}/pool/{ip}](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ip-pools/delete-v3-domains--name--pool--ip-.md): The behavior of the endpoint depends on the value of the ip parameter. It can be one of the following: * a valid IP address: this IP address will be removed from the domain pool. * string all: the entire domain pool will be removed. As far as the system is concerned, such domain will no longer exist. * string ip_pool: the DIPP which is currently linked to the domain will be unlinked. ### Removing An IP Note that it's impossible to alter domain IPs if a DIPP is linked to the domain. If the account is not eligible for shared IPs, additional rules apply: * removing the last IP from the domain is not allowed; * if all of the remaining dedicated IPs are on warmup, an extra IP might be added to the domain pool. ### Unlinking The DIPP The account must have 'DIPPs' feature enabled. Either ip or pool_id query parameter must be specified, but not both. If the special value shared is used for the replacement IP, the account must be eligible for shared IPs. In this case the system will assign a shared IP as the replacement. ## Get the dedicated IP pool used for spillover for a domain - [GET /v3/ips/domain/{name}](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/get-v3-ips-domain--name-.md): This endpoint retrieves the DIPP spillover settings for a specific domain. ## Set or modify the dediciated IP pool used for spillover for a domain - [PATCH /v3/ips/domain/{name}](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/patch-v3-ips-domain--name-.md): This endpoint allows you to set or update the DIPP spillover settings for a specific domain. You can specify the ID of the IP pool that spillover IPs are assigned to. The IP pool must contain at least one fully warmed IP address to be valild. To disable DIPP spillover, set the pool_id to an empty string (""). ## Remove an IP from the domain pool, unlink a DIPP or remove the domain pool - [DELETE /v3/domains/{name}/ips/{ip}](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/delete-v3-domains--name--ips--ip-.md): The behavior of the endpoint depends on the value of the ip parameter. It can be one of the following: * a valid IP address: this IP address will be removed from the domain pool. * string all: the entire domain pool will be removed. As far as the system is concerned, such domain will no longer exist. * string ip_pool: the DIPP which is currently linked to the domain will be unlinked. ### Removing An IP Note that it's impossible to alter domain IPs if a DIPP is linked to the domain. If the account is not eligible for shared IPs, additional rules apply: * removing the last IP from the domain is not allowed; * if all of the remaining dedicated IPs are on warmup, an extra IP might be added to the domain pool. ### Unlinking The DIPP The account must have 'DIPPs' feature enabled. Either ip or pool_id query parameter must be specified, but not both. If the special value shared is used for the replacement IP, the account must be eligible for shared IPs. In this case the system will assign a shared IP as the replacement. ## Remove an IP from the domain pool, unlink a DIPP or remove the domain pool - [DELETE /v3/domains/{name}/pool/{ip}](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/delete-v3-domains--name--pool--ip-.md): The behavior of the endpoint depends on the value of the ip parameter. It can be one of the following: * a valid IP address: this IP address will be removed from the domain pool. * string all: the entire domain pool will be removed. As far as the system is concerned, such domain will no longer exist. * string ip_pool: the DIPP which is currently linked to the domain will be unlinked. ### Removing An IP Note that it's impossible to alter domain IPs if a DIPP is linked to the domain. If the account is not eligible for shared IPs, additional rules apply: * removing the last IP from the domain is not allowed; * if all of the remaining dedicated IPs are on warmup, an extra IP might be added to the domain pool. ### Unlinking The DIPP The account must have 'DIPPs' feature enabled. Either ip or pool_id query parameter must be specified, but not both. If the special value shared is used for the replacement IP, the account must be eligible for shared IPs. In this case the system will assign a shared IP as the replacement. ## Get DIPP spillover settings for an account - [GET /v3/ips/account/settings](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/get-v3-ips-account-settings.md): This endpoint retrieves the DIPP spillover settings for a specific account. ## Set or Modify the dedicated IP pool used for IP spillover - [PATCH /v3/ips/account/settings](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/patch-v3-ips-account-settings.md): This endpoint allows you to set or update the DIPP spillover settings for an account . You can specify the ID of the IP pool that spillover IPs are assigned to. The IP pool must contain at least one fully warmed IP address to be valid. To disable DIPP spillover, set the pool_id to an empty string (""). ## List account IPs - [GET /v3/ips](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/get-v3-ips.md): assignable_to_pool in response lists which IPs can be assigned to DIPPs; this field is present only if the account has 'DIPPs' feature enabled. total_count contains the number of items returned in items (this depends on the filters applied). ## Get details about account IP - [GET /v3/ips/{ip}](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/get-v3-ips--ip-.md) ## Get all domains of an account where a specific IP is assigned - [GET /v3/ips/{ip}/domains](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/get-v3-ips--ip--domains.md): The IP must belong to the account. Matching domains are ordered by increasing id, then the limit and skip parameters are applied. If the search parameter is present, it is used to limit the results to domains whose names match the search query. The search query is split into words by whitespace and punctuation, then the logical OR is applied. ## Assign an IP to all account domains - [POST /v3/ips/{ip}/domains](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/post-v3-ips--ip--domains.md): The IP must belong to the account. ## Remove an IP from all account domains - [DELETE /v3/ips/{ip}/domains](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/delete-v3-ips--ip--domains.md): The IP must belong to the account. If the alternative parameter is present, it is used to replace the removed ip on all domains. ## Place account IP into a dedicated IP band - [POST /v3/ips/{addr}/ip_band](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/post-v3-ips--addr--ip-band.md): The Dedicated IP Bands feature must be enabled for the account. The IP must be a dedicated one belonging to the account. ## Return the number of IPs available to the account per its billing plan - [GET /v3/ips/request/new](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/get-v3-ips-request-new.md): This endpoint remains active for backwards compatibility. Do not use it in new code. Field shared in the response is deprecated and should not be used. ## Add a new dedicated IP to the account - [POST /v3/ips/request/new](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/post-v3-ips-request-new.md): A new IP can be assigned only if billing limits allow that. ## List account IPs - detailed view - [GET /v3/ips/details/all](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/get-v3-ips-details-all.md): List IPs belonging to the account and subaccounts. For IPs linked to subaccounts, there will be an additional record returned per subaccount The detailed IP view feature must be enabled for the account. ## Update subaccount IP assignments - [PATCH /v3/ips/subaccounts](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/ips/patch-v3-ips-subaccounts.md): #### Description Links and/or unlinks dedicated IPs to/from one or more subaccounts in a single operation. IPs linked to subaccounts can be linked to subaccount domains and placed in subaccount IP pools. The account must have the centralized IP assignment feature enabled. Either subaccount_id (one or more) or all_subaccounts=true must be specified, but not both. When all_subaccounts=true or over 100 subaccounts are specified, the operation is applied to every subaccount asynchronously and the response will contain 'queued' instead of 'success'. Rules for linking an IP: The IP must be a dedicated IP belonging to the parent account. The IP must not be assigned to a Dynamic IP Pool on the parent account. Rules for unlinking an IP: The IP must not be assigned to any IP pools on the subaccount. The IP must not be assigned to any domains on the subaccount. #### Request Schema Request parameters are encoded as form data. Name | Description | Required | Type --- | --- | --- | --- subaccount_id | Id of a subaccount to update (may be specified multiple times). Required unless all_subaccounts is true. | false | string all_subaccounts | When true, applies the operation to all subaccounts of the parent account asynchronously. Cannot be combined with subaccount_id. | false | string link_ip | Dedicated IP address to link to the subaccount (may be specified multiple times) | false | string unlink_ip | Dedicated IP address to unlink from the subaccount (may be specified multiple times) | false | string