ruby

Choose Language

Ips Calls

/ips/list.json

Lists your dedicated IPs.

Example Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' result = mandrill.ips.list # [{"warmup"=> # {"start_at"=>"2013-03-01 12:00:01", # "end_at"=>"2013-03-31 12:00:01", # "warming_up"=>true}, # "ip"=>"127.0.0.1", # "custom_dns"=>{"error"=>"example error", "valid"=>true, "enabled"=>true}, # "created_at"=>"2013-01-01 15:50:21", # "pool"=>"Main Pool", # "domain"=>"mail1.example.mandrillapp.com"}] rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key raise end
Parameters
No parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' ip = "example ip" result = mandrill.ips.info ip # {"custom_dns"=>{"enabled"=>true, "error"=>"example error", "valid"=>true}, # "pool"=>"Main Pool", # "warmup"=> # {"start_at"=>"2013-03-01 12:00:01", # "warming_up"=>true, # "end_at"=>"2013-03-31 12:00:01"}, # "domain"=>"mail1.example.mandrillapp.com", # "created_at"=>"2013-01-01 15:50:21", # "ip"=>"127.0.0.1"} rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key raise end
Parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' warmup = true pool = "Main Pool" result = mandrill.ips.provision warmup, pool # {"requested_at"=>"2013-01-01 01:52:21"} rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::PoorReputationError - This feature is not available for accounts with a poor reputation. raise end
Parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' ip = "127.0.0.1" result = mandrill.ips.start_warmup ip # {"domain"=>"mail1.example.mandrillapp.com", # "pool"=>"Main Pool", # "custom_dns"=>{"enabled"=>true, "valid"=>true, "error"=>"example error"}, # "created_at"=>"2013-01-01 15:50:21", # "warmup"=> # {"warming_up"=>true, # "end_at"=>"2013-03-31 12:00:01", # "start_at"=>"2013-03-01 12:00:01"}, # "ip"=>"127.0.0.1"} rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key raise end
Parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' ip = "127.0.0.1" result = mandrill.ips.cancel_warmup ip # {"pool"=>"Main Pool", # "ip"=>"127.0.0.1", # "custom_dns"=>{"valid"=>true, "enabled"=>true, "error"=>"example error"}, # "warmup"=> # {"start_at"=>"2013-03-01 12:00:01", # "warming_up"=>true, # "end_at"=>"2013-03-31 12:00:01"}, # "created_at"=>"2013-01-01 15:50:21", # "domain"=>"mail1.example.mandrillapp.com"} rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key raise end
Parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' ip = "127.0.0.1" pool = "Main Pool" create_pool = true result = mandrill.ips.set_pool ip, pool, create_pool # {"custom_dns"=>{"error"=>"example error", "valid"=>true, "enabled"=>true}, # "created_at"=>"2013-01-01 15:50:21", # "warmup"=> # {"start_at"=>"2013-03-01 12:00:01", # "end_at"=>"2013-03-31 12:00:01", # "warming_up"=>true}, # "pool"=>"Main Pool", # "ip"=>"127.0.0.1", # "domain"=>"mail1.example.mandrillapp.com"} rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::InvalidEmptyDefaultPoolError - You cannot remove the last IP from your default IP pool. raise end
Parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' ip = "127.0.0.1" result = mandrill.ips.delete ip # {"ip"=>"127.0.0.1", "deleted"=>true} rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key raise end
Parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' result = mandrill.ips.list_pools # [{"ips"=> # [{"pool"=>"Main Pool", # "warmup"=> # {"warming_up"=>true, # "end_at"=>"2013-03-31 12:00:01", # "start_at"=>"2013-03-01 12:00:01"}, # "custom_dns"=>{"error"=>"example error", "valid"=>true, "enabled"=>true}, # "ip"=>"127.0.0.1", # "domain"=>"mail1.example.mandrillapp.com", # "created_at"=>"2013-01-01 15:50:21"}], # "created_at"=>"2013-01-01 12:15:12", # "name"=>"Main Pool"}] rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key raise end
Parameters
No parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' pool = "Main Pool" result = mandrill.ips.pool_info pool # {"ips"=> # [{"ip"=>"127.0.0.1", # "created_at"=>"2013-01-01 15:50:21", # "domain"=>"mail1.example.mandrillapp.com", # "custom_dns"=>{"error"=>"example error", "enabled"=>true, "valid"=>true}, # "warmup"=> # {"start_at"=>"2013-03-01 12:00:01", # "end_at"=>"2013-03-31 12:00:01", # "warming_up"=>true}, # "pool"=>"Main Pool"}], # "created_at"=>"2013-01-01 12:15:12", # "name"=>"Main Pool"} rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key raise end
Parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' pool = "New Pool" result = mandrill.ips.create_pool pool # {"created_at"=>"2013-01-01 12:15:12", # "ips"=> # [{"ip"=>"127.0.0.1", # "warmup"=> # {"start_at"=>"2013-03-01 12:00:01", # "end_at"=>"2013-03-31 12:00:01", # "warming_up"=>true}, # "custom_dns"=>{"enabled"=>true, "error"=>"example error", "valid"=>true}, # "created_at"=>"2013-01-01 15:50:21", # "domain"=>"mail1.example.mandrillapp.com", # "pool"=>"Main Pool"}], # "name"=>"Main Pool"} rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key raise end
Parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' pool = "Delete Pool" result = mandrill.ips.delete_pool pool # {"pool"=>"Delete Pool", "deleted"=>true} rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::InvalidDeleteNonEmptyPoolError - Non-empty pools cannot be deleted. raise end
Parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' ip = "127.0.0.1" domain = "mail1.example.mandrillapp.com" result = mandrill.ips.check_custom_dns ip, domain # {"error"=>"mail128.example.mandrillapp.com does not exist", "valid"=>true} rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::UnknownIPError - No dedicated IP exists with the IP address 127.0.0.1 raise end
Parameters
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 Call

begin mandrill = Mandrill::API.new 'YOUR_API_KEY' ip = "127.0.0.1" domain = "example domain" result = mandrill.ips.set_custom_dns ip, domain # {"domain"=>"mail1.example.mandrillapp.com", # "pool"=>"Main Pool", # "ip"=>"127.0.0.1", # "warmup"=> # {"start_at"=>"2013-03-01 12:00:01", # "warming_up"=>true, # "end_at"=>"2013-03-31 12:00:01"}, # "custom_dns"=>{"error"=>"example error", "valid"=>true, "enabled"=>true}, # "created_at"=>"2013-01-01 15:50:21"} rescue Mandrill::Error => e # Mandrill errors are thrown as exceptions puts "A mandrill error occurred: #{e.class} - #{e.message}" # A mandrill error occurred: Mandrill::InvalidCustomDNSPendingError - A custom DNS change for this dedicated IP is currently pending. raise end
Parameters
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.