JSON

Choose Language

Ips Calls

/ips/list.json

Lists your dedicated IPs.

Example Request JSON

{"key":"example key"}

Example Response JSON

[{"ip":"127.0.0.1","created_at":"2013-01-01 15:50:21","pool":"Main Pool","domain":"mail1.example.mandrillapp.com","custom_dns":{"enabled":true,"valid":true,"error":"example error"},"warmup":{"warming_up":true,"start_at":"2013-03-01 12:00:01","end_at":"2013-03-31 12:00:01"}}]

Example Error Response JSON

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid api key
Return Value
array an array of structs for each dedicated IP
return[] struct information about a single dedicated IP
ip string the ip address
created_at string the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
pool string the name of the pool that this dedicated IP belongs to
domain string the domain name (reverse dns) of this dedicated IP
custom_dns struct information about the ip's custom dns, if it has been configured
enabled boolean a boolean indicating whether custom dns has been configured for this ip
valid boolean whether the ip's custom dns is currently valid
error string if the ip's custom dns is invalid, this will include details about the error
warmup struct information about the ip's warmup status
warming_up boolean whether the ip is currently in warmup mode
start_at string the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
end_at string the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/info.json

Retrieves information about a single dedicated ip.

Example Request JSON

{"key":"example key","ip":"example ip"}

Example Response JSON

{"ip":"127.0.0.1","created_at":"2013-01-01 15:50:21","pool":"Main Pool","domain":"mail1.example.mandrillapp.com","custom_dns":{"enabled":true,"valid":true,"error":"example error"},"warmup":{"warming_up":true,"start_at":"2013-03-01 12:00:01","end_at":"2013-03-31 12:00:01"}}

Example Error Response JSON

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid api key
ip* string a dedicated IP address
Return Value
struct Information about the dedicated ip
ip string the ip address
created_at string the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
pool string the name of the pool that this dedicated IP belongs to
domain string the domain name (reverse dns) of this dedicated IP
custom_dns struct information about the ip's custom dns, if it has been configured
enabled boolean a boolean indicating whether custom dns has been configured for this ip
valid boolean whether the ip's custom dns is currently valid
error string if the ip's custom dns is invalid, this will include details about the error
warmup struct information about the ip's warmup status
warming_up boolean whether the ip is currently in warmup mode
start_at string the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
end_at string the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/provision.json

Requests an additional dedicated IP for your account. Accounts may have one outstanding request at any time, and provisioning requests are processed within 24 hours.

Example Request JSON

{"key":"example key","warmup":true,"pool":"Main Pool"}

Example Response JSON

{"requested_at":"2013-01-01 01:52:21"}

Example Error Response JSON

{"status":"error","code":25,"name":"PoorReputation","message":"This feature is not available for accounts with a poor reputation."}
Parameters
key* string a valid api key
warmup boolean whether to enable warmup mode for the ip
pool string the id of the pool to add the dedicated ip to, or null to use your account's default pool
Return Value
struct a description of the provisioning request that was created
requested_at string the date and time that the request was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format
Errors
IP_ProvisionLimit A dedicated IP cannot be provisioned while another request is pending.
Unknown_Pool The provided dedicated IP pool does not exist.
PaymentRequired The requested feature requires payment.
Invalid_Key The provided API key is not a valid Mandrill API key
NoSendingHistory The user hasn't started sending yet.
PoorReputation The user's reputation is too low to continue.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/start-warmup.json

Begins the warmup process for a dedicated IP. During the warmup process, Mandrill will gradually increase the percentage of your mail that is sent over the warming-up IP, over a period of roughly 30 days. The rest of your mail will be sent over shared IPs or other dedicated IPs in the same pool.

Example Request JSON

{"key":"example key","ip":"127.0.0.1"}

Example Response JSON

{"ip":"127.0.0.1","created_at":"2013-01-01 15:50:21","pool":"Main Pool","domain":"mail1.example.mandrillapp.com","custom_dns":{"enabled":true,"valid":true,"error":"example error"},"warmup":{"warming_up":true,"start_at":"2013-03-01 12:00:01","end_at":"2013-03-31 12:00:01"}}

Example Error Response JSON

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid api key
ip* string a dedicated ip address
Return Value
struct Information about the dedicated IP
ip string the ip address
created_at string the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
pool string the name of the pool that this dedicated IP belongs to
domain string the domain name (reverse dns) of this dedicated IP
custom_dns struct information about the ip's custom dns, if it has been configured
enabled boolean a boolean indicating whether custom dns has been configured for this ip
valid boolean whether the ip's custom dns is currently valid
error string if the ip's custom dns is invalid, this will include details about the error
warmup struct information about the ip's warmup status
warming_up boolean whether the ip is currently in warmup mode
start_at string the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
end_at string the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Unknown_IP The provided dedicated IP does not exist.
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/cancel-warmup.json

Cancels the warmup process for a dedicated IP.

Example Request JSON

{"key":"example key","ip":"127.0.0.1"}

Example Response JSON

{"ip":"127.0.0.1","created_at":"2013-01-01 15:50:21","pool":"Main Pool","domain":"mail1.example.mandrillapp.com","custom_dns":{"enabled":true,"valid":true,"error":"example error"},"warmup":{"warming_up":true,"start_at":"2013-03-01 12:00:01","end_at":"2013-03-31 12:00:01"}}

Example Error Response JSON

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid api key
ip* string a dedicated ip address
Return Value
struct Information about the dedicated IP
ip string the ip address
created_at string the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
pool string the name of the pool that this dedicated IP belongs to
domain string the domain name (reverse dns) of this dedicated IP
custom_dns struct information about the ip's custom dns, if it has been configured
enabled boolean a boolean indicating whether custom dns has been configured for this ip
valid boolean whether the ip's custom dns is currently valid
error string if the ip's custom dns is invalid, this will include details about the error
warmup struct information about the ip's warmup status
warming_up boolean whether the ip is currently in warmup mode
start_at string the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
end_at string the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Unknown_IP The provided dedicated IP does not exist.
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/set-pool.json

Moves a dedicated IP to a different pool.

Example Request JSON

{"key":"example key","ip":"127.0.0.1","pool":"Main Pool","create_pool":true}

Example Response JSON

{"ip":"127.0.0.1","created_at":"2013-01-01 15:50:21","pool":"Main Pool","domain":"mail1.example.mandrillapp.com","custom_dns":{"enabled":true,"valid":true,"error":"example error"},"warmup":{"warming_up":true,"start_at":"2013-03-01 12:00:01","end_at":"2013-03-31 12:00:01"}}

Example Error Response JSON

{"status":"error","code":16,"name":"Invalid_EmptyDefaultPool","message":"You cannot remove the last IP from your default IP pool."}
Parameters
key* string a valid api key
ip* string a dedicated ip address
pool* string the name of the new pool to add the dedicated ip to
create_pool boolean whether to create the pool if it does not exist; if false and the pool does not exist, an Unknown_Pool will be thrown.
Return Value
struct Information about the updated state of the dedicated IP
ip string the ip address
created_at string the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
pool string the name of the pool that this dedicated IP belongs to
domain string the domain name (reverse dns) of this dedicated IP
custom_dns struct information about the ip's custom dns, if it has been configured
enabled boolean a boolean indicating whether custom dns has been configured for this ip
valid boolean whether the ip's custom dns is currently valid
error string if the ip's custom dns is invalid, this will include details about the error
warmup struct information about the ip's warmup status
warming_up boolean whether the ip is currently in warmup mode
start_at string the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
end_at string the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Unknown_IP The provided dedicated IP does not exist.
Unknown_Pool The provided dedicated IP pool does not exist.
Invalid_Key The provided API key is not a valid Mandrill API key
Invalid_EmptyDefaultPool You cannot remove the last IP from your default IP pool.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/delete.json

Deletes a dedicated IP. This is permanent and cannot be undone.

Example Request JSON

{"key":"example key","ip":"127.0.0.1"}

Example Response JSON

{"ip":"127.0.0.1","deleted":true}

Example Error Response JSON

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid api key
ip* string the dedicated ip to remove from your account
Return Value
struct a description of the ip that was removed from your account.
ip string the ip address
deleted string a boolean indicating whether the ip was successfully deleted
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/list-pools.json

Lists your dedicated IP pools.

Example Request JSON

{"key":"example key"}

Example Response JSON

[{"name":"Main Pool","created_at":"2013-01-01 12:15:12","ips":[{"ip":"127.0.0.1","created_at":"2013-01-01 15:50:21","pool":"Main Pool","domain":"mail1.example.mandrillapp.com","custom_dns":{"enabled":true,"valid":true,"error":"example error"},"warmup":{"warming_up":true,"start_at":"2013-03-01 12:00:01","end_at":"2013-03-31 12:00:01"}}]}]

Example Error Response JSON

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid api key
Return Value
array the dedicated IP pools for your account, up to a maximum of 1,000
return[] struct information about each dedicated IP pool
name string this pool's name
created_at string the date and time that this pool was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format
ips array the dedicated IPs in this pool
ips[] struct information about each dedicated IP
ip string the ip address
created_at string the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
pool string the name of the pool that this dedicated IP belongs to
domain string the domain name (reverse dns) of this dedicated IP
custom_dns struct information about the ip's custom dns, if it has been configured
enabled boolean a boolean indicating whether custom dns has been configured for this ip
valid boolean whether the ip's custom dns is currently valid
error string if the ip's custom dns is invalid, this will include details about the error
warmup struct information about the ip's warmup status
warming_up boolean whether the ip is currently in warmup mode
start_at string the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
end_at string the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/pool-info.json

Describes a single dedicated IP pool.

Example Request JSON

{"key":"example key","pool":"Main Pool"}

Example Response JSON

{"name":"Main Pool","created_at":"2013-01-01 12:15:12","ips":[{"ip":"127.0.0.1","created_at":"2013-01-01 15:50:21","pool":"Main Pool","domain":"mail1.example.mandrillapp.com","custom_dns":{"enabled":true,"valid":true,"error":"example error"},"warmup":{"warming_up":true,"start_at":"2013-03-01 12:00:01","end_at":"2013-03-31 12:00:01"}}]}

Example Error Response JSON

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid api key
pool* string a pool name
Return Value
struct Information about the dedicated ip pool
name string this pool's name
created_at string the date and time that this pool was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format
ips array the dedicated IPs in this pool
ips[] struct information about each dedicated IP
ip string the ip address
created_at string the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
pool string the name of the pool that this dedicated IP belongs to
domain string the domain name (reverse dns) of this dedicated IP
custom_dns struct information about the ip's custom dns, if it has been configured
enabled boolean a boolean indicating whether custom dns has been configured for this ip
valid boolean whether the ip's custom dns is currently valid
error string if the ip's custom dns is invalid, this will include details about the error
warmup struct information about the ip's warmup status
warming_up boolean whether the ip is currently in warmup mode
start_at string the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
end_at string the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Unknown_Pool The provided dedicated IP pool does not exist.
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/create-pool.json

Creates a pool and returns it. If a pool already exists with this name, no action will be performed.

Example Request JSON

{"key":"example key","pool":"New Pool"}

Example Response JSON

{"name":"Main Pool","created_at":"2013-01-01 12:15:12","ips":[{"ip":"127.0.0.1","created_at":"2013-01-01 15:50:21","pool":"Main Pool","domain":"mail1.example.mandrillapp.com","custom_dns":{"enabled":true,"valid":true,"error":"example error"},"warmup":{"warming_up":true,"start_at":"2013-03-01 12:00:01","end_at":"2013-03-31 12:00:01"}}]}

Example Error Response JSON

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid api key
pool* string the name of a pool to create
Validation: required
Return Value
struct Information about the dedicated ip pool
name string this pool's name
created_at string the date and time that this pool was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format
ips array the dedicated IPs in this pool
ips[] struct information about each dedicated IP
ip string the ip address
created_at string the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
pool string the name of the pool that this dedicated IP belongs to
domain string the domain name (reverse dns) of this dedicated IP
custom_dns struct information about the ip's custom dns, if it has been configured
enabled boolean a boolean indicating whether custom dns has been configured for this ip
valid boolean whether the ip's custom dns is currently valid
error string if the ip's custom dns is invalid, this will include details about the error
warmup struct information about the ip's warmup status
warming_up boolean whether the ip is currently in warmup mode
start_at string the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
end_at string the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/delete-pool.json

Deletes a pool. A pool must be empty before you can delete it, and you cannot delete your default pool.

Example Request JSON

{"key":"example key","pool":"Delete Pool"}

Example Response JSON

{"pool":"Delete Pool","deleted":true}

Example Error Response JSON

{"status":"error","code":18,"name":"Invalid_DeleteNonEmptyPool","message":"Non-empty pools cannot be deleted."}
Parameters
key* string a valid api key
pool* string the name of the pool to delete
Return Value
struct information about the status of the pool that was deleted
pool string the name of the pool
deleted boolean whether the pool was deleted
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Pool The provided dedicated IP pool does not exist.
Invalid_DeleteDefaultPool The default pool cannot be deleted.
Invalid_DeleteNonEmptyPool Non-empty pools cannot be deleted.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/check-custom-dns.json

Tests whether a domain name is valid for use as the custom reverse DNS for a dedicated IP.

Example Request JSON

{"key":"example key","ip":"127.0.0.1","domain":"mail1.example.mandrillapp.com"}

Example Response JSON

{"valid":true,"error":"mail128.example.mandrillapp.com does not exist"}

Example Error Response JSON

{"status":"error","code":13,"name":"Unknown_IP","message":"No dedicated IP exists with the IP address 127.0.0.1"}
Parameters
key* string a valid api key
ip* string a dedicated ip address
Validation: required
domain* string the domain name to test
Validation: required, domain
Return Value
struct validation results for the domain
valid string whether the domain name has a correctly-configured A record pointing to the ip address
error string if valid is false, this will contain details about why the domain's A record is incorrect
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_IP The provided dedicated IP does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/ips/set-custom-dns.json

Configures the custom DNS name for a dedicated IP.

Example Request JSON

{"key":"example key","ip":"127.0.0.1","domain":"example domain"}

Example Response JSON

{"ip":"127.0.0.1","created_at":"2013-01-01 15:50:21","pool":"Main Pool","domain":"mail1.example.mandrillapp.com","custom_dns":{"enabled":true,"valid":true,"error":"example error"},"warmup":{"warming_up":true,"start_at":"2013-03-01 12:00:01","end_at":"2013-03-31 12:00:01"}}

Example Error Response JSON

{"status":"error","code":20,"name":"Invalid_CustomDNSPending","message":"A custom DNS change for this dedicated IP is currently pending."}
Parameters
key* string a valid api key
ip* string a dedicated ip address
Validation: required
domain* string a domain name to set as the dedicated IP's custom dns name.
Validation: required, domain
Return Value
struct information about the dedicated IP's new configuration
ip string the ip address
created_at string the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
pool string the name of the pool that this dedicated IP belongs to
domain string the domain name (reverse dns) of this dedicated IP
custom_dns struct information about the ip's custom dns, if it has been configured
enabled boolean a boolean indicating whether custom dns has been configured for this ip
valid boolean whether the ip's custom dns is currently valid
error string if the ip's custom dns is invalid, this will include details about the error
warmup struct information about the ip's warmup status
warming_up boolean whether the ip is currently in warmup mode
start_at string the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
end_at string the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_IP The provided dedicated IP does not exist.
Invalid_CustomDNS The domain name is not configured for use as the dedicated IP's custom reverse DNS.
Invalid_CustomDNSPending A custom DNS change for this dedicated IP is currently pending.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.