JSON

Choose Language

Rejects Calls

/rejects/add.json

Adds an email to your email rejection blacklist. Addresses that you add manually will never expire and there is no reputation penalty for removing them from your blacklist. Attempting to blacklist an address that has been whitelisted will have no effect.

Example Request JSON

{"key":"example key","email":"example email","comment":"example comment","subaccount":"cust-123"}

Example Response JSON

{"email":"example email","added":true}

Example Error Response JSON

{"status":"error","code":12,"name":"Unknown_Subaccount","message":"No subaccount exists with the id 'customer-123'"}
Parameters
key* string a valid api key
email* string an email address to block
Validation: required
comment string an optional comment describing the rejection
subaccount string an optional unique identifier for the subaccount to limit the blacklist entry
Validation: maxlength(255)
Return Value
struct a status object containing the address and the result of the operation
email string the email address you provided
added boolean whether the operation succeeded
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Subaccount The provided subaccount id 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.

/rejects/list.json

Retrieves your email rejection blacklist. You can provide an email address to limit the results. Returns up to 1000 results. By default, entries that have expired are excluded from the results; set include_expired to true to include them.

Example Request JSON

{"key":"example key","email":"example email","include_expired":true,"subaccount":"cust-123"}

Example Response JSON

[{"email":"example email","reason":"hard-bounce","detail":"550 mailbox does not exist","created_at":"2013-01-01 15:30:27","last_event_at":"2013-01-01 15:30:27","expires_at":"2013-01-01 15:30:49","expired":false,"sender":{"address":"sender.example@mandrillapp.com","created_at":"2013-01-01 15:30:27","sent":42,"hard_bounces":42,"soft_bounces":42,"rejects":42,"complaints":42,"unsubs":42,"opens":42,"clicks":42,"unique_opens":42,"unique_clicks":42},"subaccount":"example subaccount"}]

Example Error Response JSON

{"status":"error","code":-2,"name":"ServiceUnavailable","message":"Service Temporarily Unavailable"}
Parameters
key* string a valid api key
email string an optional email address to search by
include_expired boolean whether to include rejections that have already expired.
subaccount string an optional unique identifier for the subaccount to limit the blacklist
Validation: maxlength(255)
Return Value
array Up to 1000 rejection entries
return[] struct the information for each rejection blacklist entry
email string the email that is blocked
reason string the type of event (hard-bounce, soft-bounce, spam, unsub, custom) that caused this rejection
detail string extended details about the event, such as the SMTP diagnostic for bounces or the comment for manually-created rejections
created_at string when the email was added to the blacklist
last_event_at string the timestamp of the most recent event that either created or renewed this rejection
expires_at string when the blacklist entry will expire (this may be in the past)
expired boolean whether the blacklist entry has expired
sender struct the sender that this blacklist entry applies to, or null if none.
address string the sender's email address
created_at string the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format
sent integer the total number of messages sent by this sender
hard_bounces integer the total number of hard bounces by messages by this sender
soft_bounces integer the total number of soft bounces by messages by this sender
rejects integer the total number of rejected messages by this sender
complaints integer the total number of spam complaints received for messages by this sender
unsubs integer the total number of unsubscribe requests received for messages by this sender
opens integer the total number of times messages by this sender have been opened
clicks integer the total number of times tracked URLs in messages by this sender have been clicked
unique_opens integer the number of unique opens for emails sent for this sender
unique_clicks integer the number of unique clicks for emails sent for this sender
subaccount string the subaccount that this blacklist entry applies to, or null if none.
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Subaccount The provided subaccount id does not exist.
ServiceUnavailable The subsystem providing this API call is down for maintenance
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.

/rejects/delete.json

Deletes an email rejection. There is no limit to how many rejections you can remove from your blacklist, but keep in mind that each deletion has an affect on your reputation.

Example Request JSON

{"key":"example key","email":"example email","subaccount":"cust-123"}

Example Response JSON

{"email":"email@example.com","deleted":true,"subaccount":"cust-123"}

Example Error Response JSON

{"status":"error","code":12,"name":"Unknown_Subaccount","message":"No subaccount exists with the id 'customer-123'"}
Parameters
key* string a valid api key
email* string an email address
Validation: required
subaccount string an optional unique identifier for the subaccount to limit the blacklist deletion
Validation: maxlength(255)
Return Value
struct a status object containing the address and whether the deletion succeeded.
email string the email address that was removed from the blacklist
deleted boolean whether the address was deleted successfully.
subaccount string the subaccount blacklist that the address was removed from, if any
Errors
Invalid_Reject The requested email is not in the rejection list
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Subaccount The provided subaccount id 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.