Mandrill FAQs

Here are some example rules to help you get started.

Add an Automatic Unsubscribe Footer

You can use the Sending Default option to add an automatic unsubscribe footer. You may not want to append an unsubscribe footer to every email, though. You can use Rules to enable or disable the unsubscribe footer for some emails. For example, add the unsubscribe footer only to your emails tagged "marketing":

create a new webhook

Add a Tag for Emails Sent with SMTP

If you cannot add Mandrill's custom SMTP headers to influence sending behavior and customize your emails, use a rule instead. Here is an example of arule that adds the tag password-reset to all emails from the sender [email protected]:

Apply a Template With Editable Content Blocks

Templates allow you to create your email design and store commonly used content to re-use for different transactional emails. You can store templates in Mandrill, and then send emails using the template and providing dynamic, recipient-specific content.

The following rule applies theverify-email template to any messages that have the word verification anywhere in the subject line and places the message content into the editable template block called main.

Now, when you send a message with a subject line like "Your verification email from domain.com", this rule will be applied.

Reject Emails With an Empty Subject Line

Rule conditions also support null values. To create a new rule that rejects any emails that do not have any content in the subject line, set up your rule like the one in this example, but do not type any text or click into the last text field after the matches drop-down menu:

Blacklist a Domain

Mandrill allows you to add email addresses to your Rejection Blacklist manually, but does not allow you to add an entire domain. You can set up a rule to reject any emails from a particular domain. For example, you can sendtest emails to a domain that doesnot exist or attempting to block unwanted senders from relaying email through your Mandrill account.

Run a Test on a Random Sample of Emails

In situations where youwant to change your email, but you are not sure if the change will be effective. Will recipients open and click more, or will they click less? Maybe you want to do an A/B split test on your change, or maybe you want to limit the change to some small percentage of your emails as a trial.

Use random sampleas part of your rule conditions, along with the other criteria for the rule. Then, you can do things likechangina template or modifyinga Google Analytics tracking, and those changes will only apply to that random subset.

After the test generates data, use stats comparison reports to chart and compare the differences between the groups. When you are ready to pick a winner, just change the winning rule to match all the time and delete the others.

Create API key, Sender, or Domain-Specific Webhooks

This is useful if you only want events tied to a certain domain, sender email address, or API key to post to a webhook URL. For example, you might want to have all email events from your test environment only POST to a specific test endpoint on your server. In this case, that POSTs to your test endpoint. When creating the webhook, do not select any events. For example:

Then, create a rule that looks for any emails sent from the API key being used for your testing environment and choose your test webhook URL:

You need to create a new rule for each event you want to receive information about (sent, bounced, opened, etc.).

Follow the same steps to create a domain-specific webhook. This time, your rule conditions might look like this:

Below is an example of using PHPMailer to send through Mandrill (adapted from the PHPMailer examples):

<?php

require 'class.phpmailer.php';

$mail = new PHPMailer;

$mail->IsSMTP(); // Set mailer to use SMTP

$mail->Host = 'smtp.mandrillapp.com'; // Specify main and backup server

$mail->Port = 587; // Set the SMTP port

$mail->SMTPAuth = true; // Enable SMTP authentication

$mail->Username = 'MANDRILL_USERNAME'; // SMTP username

$mail->Password = 'MANDRILL_APIKEY'; // SMTP password

$mail->SMTPSecure = 'tls'; // Enable encryption, 'ssl' also accepted

$mail->From = '[email protected]';

$mail->FromName = 'Your From name';

$mail->AddAddress('[email protected]', 'Josh Adams'); // Add a recipient

$mail->AddAddress('[email protected]'); // Name is optional

$mail->IsHTML(true); // Set email format to HTML

$mail->Subject = 'Here is the subject';

$mail->Body = 'This is the HTML message body <strong>in bold!</strong>';

$mail->AltBody = 'This is the body in plain text for non-HTML mail clients';

if(!$mail->Send()) {

echo 'Message could not be sent.';

echo 'Mailer Error: '. $mail->ErrorInfo;

exit;

}

echo 'Message has been sent';

You can find additional examples for using PHPMailer in the PHPMailer examples folder with the PHPMailer source.

Below an example of a script to send email using the PHP SwiftMailer library to send through Mandrill:

<?php

include_once "swift_required.php";

$subject = 'Hello from Mandrill, PHP!';

$from = array('[email protected]' =>'Your Name');

$to = array(

'[email protected]' => 'Recipient1 Name',

'[email protected]' => 'Recipient2 Name'

);

$text = "Mandrill speaks plaintext";

$html = "<em>Mandrill speaks <strong>HTML</strong></em>";

$transport = Swift_SmtpTransport::newInstance('smtp.mandrillapp.com', 587);

$transport->setUsername('MANDRILL_USERNAME');

$transport->setPassword('MANDRILL_PASSWORD');

$swift = Swift_Mailer::newInstance($transport);

$message = new Swift_Message($subject);

$message->setFrom($from);

$message->setBody($html, 'text/html');

$message->setTo($to);

$message->addPart($text, 'text/plain');

if ($recipients = $swift->send($message, $failures))

{

echo 'Message successfully sent!';

} else {

echo "There was an error:\n";

print_r($failures);

}

?>

If you are using Ruby on Rails or NodeJS, you can configure sending through your Mandrill account via SMTP.

Port 25 is used in these examples, but you can connect to Mandrill on other ports if needed, so use whichever works for your particular configuration.

Ruby on Rails

Rails comes ready to send email out of the box, you just need to decide what environments will be sending email via Mandrill: production is a no-brainer, but development may only use Mandrill on occasion to make sure something works, and test should probably never use it (test suites should not rely on external services, etc.)

Which file you edit is determined by your environment choices:

production: config/environments/production.rb

test: config/environments/test.rb

development: config/environments/development.rb

all: config/application.rb (not recommended)

Code

# production.rb, test.rb, development.rb or application.rb

YourApp::Application.configure do

config.action_mailer.smtp_settings = {

:address => "smtp.mandrillapp.com",

:port => 25, # ports 587 and 2525 are also supported with STARTTLS

:enable_starttls_auto => true, # detects and uses STARTTLS

:user_name => "MANDRILL_USERNAME",

:password => "MANDRILL_PASSWORD", # SMTP password is any valid API key

:authentication => 'login', # Mandrill supports 'plain' or 'login'

:domain => 'yourdomain.com', # your domain to identify your server when connecting

}

#

end

# app/mailers/your_mailer.rb

class YourMailer < ActionMailer::Base

def email_name

mail:subject => "Mandrill rides the Rails!",

:to => "[email protected]",

:from => "[email protected]"

end

end

# In a controller: YourMailer.email_name.deliver

NodeJS

For Node well be using the node_mailer library, installed via npm. To install npm:

$ curl http://npmjs.org/install.sh | sh

To install node_mailer:

$ npm install mailer

Code

// mailer.js

var mailer = require("mailer")

, username = "MANDRILL_USERNAME"

, password = "MANDRILL_PASSWORD";

mailer.send(

{ host: "smtp.mandrillapp.com"

, port: 25

, to: "[email protected]"

, from: "[email protected]"

, subject: "Mandrill knows Javascript!"

, body: "Hello from NodeJS!"

, authentication: "login"

, username: username

, password: password

}, function(err, result){

if(err){

console.log(err);

}

}

);

Now run like this:

$ node mailer.js

A dedicated IP is an IP address used for sending email that is only used by a single user or account. Only that user's email is sent over the IP, so the volume of mail sent from that IP and the reputation of the IP is determined only by the email sent by that user from that IP.

By default, when you send anemail through Mandrill, it's sent from one of Mandrill's shared IP addresses. These are IP addresses that are used by multiple Mandrill users, and Mandrill automatically routes your emails based on a variety of factors, including how much email issent from a particular shared IP.

A dedicated IP is not used for connecting to Mandrill to relay email, and is only used for sending email.

Whether to use a dedicated IP or not is not always straightforward.

Learn more about whether you shoulduse a dedicated IP

Mandrill signs webhook requests so you can (optionally) verify that requests are generated by Mandrill and not a third-party pretending to be Mandrill. If your application exposes sensitive data, be sure the requests are coming from Mandrill. This is not required, but offers an additional layer of verification.

Verifying Request Signatures

Mandrill includes an additional HTTP header with webhook POST requests, X-Mandrill-Signature, which will contain the signature for the request. To verify a webhook request, generate a signature using the same key that Mandrill uses and compare that to the value of the X-Mandrill-Signature header.

Get your Webhook Authentication Key

When you create a webhook, a key is automatically generated. If you are using the webhooks/add method, the key will be returned in the response. You can also view and reset the key from the Webhooks page in your account, in the Key column. To retrieve a webhook key via the Mandrill API, use webhooks/info or webhooks/list.

Generate a Signature

In your code that receives or processes webhook requests:

Create a string with the webhook's URL, exactly as you entered it in Mandrill (including any query strings, if applicable). Mandrill always signs webhook requests with the exact URL you provided when you configured the webhook. A difference as small as including or removing a trailing slash will prevent the signature from validating.

Sort the request's POST variables alphabetically by key.

Append each POST variable's key and value to the URL string, with no delimiter.

Hash the resulting string with HMAC-SHA1, using your webhook's authentication key to generate a binary signature.

Base64 encode the binary signature

Compare the binary signature that you generated to the signature provided in the X-Mandrill-Signature HTTP header.

Note: Some HMAC implementations can generate either a binary or hexadecimal signature. Mandrill generates a binary signature and then Base64-encodes it; using a hexadecimal signature will not work.

Example PHP implementation

/**

* Generates a base64-encoded signature for a Mandrill webhook request.

* @param string $webhook_key the webhook's authentication key

* @param string $url the webhook url

* @param array $params the request's POST parameters

*/

function generateSignature($webhook_key, $url, $params) {

$signed_data = $url;

ksort($params);

foreach ($params as $key => $value) {

$signed_data.= $key;

$signed_data.= $value;

}

return base64_encode(hash_hmac('sha1', $signed_data, $webhook_key, true));

}

Considerations

You can reset a webhook's authentication keyat any time. Mandrill will immediately begin using the new key to sign requests. To ensure that you donot lose any webhook batches between the time you reset your key and when you update your application to start using that new key, your webhook processor should reject batches with failed signatures with a non-200 status code. Mandrill will queue the batch and retry later, which will give you time to update your application with the new key.

Temporarily stop sending for any subaccount in the Mandrill web interface or via the Mandrill API. While sending is paused, emails will be queued into to the account's backlog. To pause sending for a subaccount, follow these steps.

Go to theSubaccounts page.

Click View Details.

Click Pause.

To resume sending, click Resume.

Delete a subaccount in the Mandrill web interface or via the API. Deleting a subaccount is permanent, so Mandrill can not recover a subaccount after it is deleted. This will not remove email activity associated with the subaccount and you can no longer search activity by the subaccount name.

To delete a subaccount, follow these steps:

Go to the Subaccountspage.

Click the Delete button next to the subaccount you want to remove.

Click Yes, delete this subaccountin the modal window that appears.

Mandrill automatically tracks activity by subaccount. You can view this activity in a few different ways.

Activity Page

Go to theActivitypage in your Mandrill account.

Choose a subaccount from the Subaccount filter to view all activity, or limit your results using a custom search query.

Subaccounts Overview Page

Go to theActivitypage in your Mandrill account.

Click on the subaccount ID or the View Details button.

webhook

The Mandrill API

Use the subaccounts/list call to view a list of current subaccounts and an activity overview for each. Use subaccounts/info to view detailed stats for a givensubaccount id.

Webhooks

If a message was sent from a subaccount, Mandrill will return the subaccount id in the msg object for events you are tracking.

If a message sent from a subaccount bounces, the recipient unsubscribes or reports the message as spam, the recipient will be moved to the Rejection Blacklist for that subaccount automatically.

Any bounces, spam complaints, or unsubscribe requests Mandrill receives for an email will only by applied to the sending subaccount's blacklist. Other subaccounts will still be able to send to that recipient without issue.

To view the Rejection Blacklist for a specific subaccount, follow these steps:

Go to the Rejection Blacklistpage.

Select the subaccount ID from the View Blacklist For Subaccount drop-down menu.

Mandrill API

You can also retrieve the rejection blacklist for a subaccount via the .

Two hourly quotas are considered for each subaccount: the primary account's quota and the subaccount's quota. If a subaccount sends a message that would put either the subaccount or the primary account over its hourly quota, the emails will be placed in the primary account's backlog. Subaccounts do not have separate backlogs.

Yes. Mandrill automatically retries failed webhook batches in an error state, but you can also stop a failed batch manually. To stop a failed webhook batch, follow these steps.

Go to theWebhookspage in your Mandrill account.

Click on the number shown under Number of events.

Click give up.

The batch will be stopped and will not be sent to the webhook URL. New events will begin posting in about one to two minutes.

Webhook and inbound route URLs should be set up to accept, at a minimum, POST requests.

When you provide the URL where you want Mandrill to POST the data for events, we will do a quick check that the URL exists by using a HEAD request (not POST). If the URL does not exist or returns something other than a 200 HTTP response to the HEAD request, Mandrill will fallback and attempt a POST request.

The POST will be the same type ofPOST as a Mandrill webhook, except that the mandrill_events parameter will be an empty array, and the POST will be signed with a generic key (with the value 'test-webhook').

For SMTP messages, you may send to up to 1,000 recipients at a time. If you are sending messagesto more recipients, simultaneous and subsequent connections are permitted.

For the API, there is no recipient limitation, but the JSON provided per API call must be less than 10MB. We strongly recommend smaller recipient batches for easier troubleshooting.

When sending messagesto multiple recipients in a single SMTP message or API call, if you do not want them to see each others information, set the preserve_recipients option to false (API) or the value of the custom header X-MC-PreserveRecipients to False (SMTP).

You can also control this option for the account as a wholeon the Sending Optionspage using the Expose The List Of Recipients When Sending To Multiple Addresses option. Select the box next to this option to allow recipients to see each others information in the To header, and deselect the box so that each recipientsees only their own information in the To header.

Mandrill records all dates and times in UTC. When viewing the activity in an account, Mandrill detects the time zone you are in based on your computer/browser settings, and will convert the times to the local time detected.

If the times are incorrect, check the system settings on the computer being used to be sure that the time is set correctly, and that you have JavaScript enabled in the browser.

A test API key is a limited API key that interacts with your account in test mode. No emails aresent when you use a test API key for sending. They will be visible in the web interface when in test mode, but not while viewing the account normally.

Yes. To temporarily pause sending for your account, clickpauseon the Dashboard of your account.

If you have items in the backlog, you will also see a button with a trashcan to clear the backlog.

Note

Cearing the backlog can not be undoneand all messages queued in the backlog willbe removed.

Yes. For webhooks in an error state, Mandrill provides the raw webhook request content and sample code so you can emulate the failed POST using cURL. To view webhook batch details, follow these steps.

Go to the Webhooks page in your Mandrill account.

Click on the number shown under Number of events.

Click the view batch button.

At the top of the page, you will see the raw webhook request generated and sent by Mandrill. You can use thecURL command at the bottom of the page to mimic the webhook POST in your own environment.

Note

If the webhook payload is too large to fit on the common command-line, we will provide a link to download it in full as a .txt file. You will need to save the file in the working directory before you run the cURL command.

A lot of users ask us whether or not they should use a dedicated IP. Unfortunately, the answer isn't always straightforward, and the real answer is that it depends.

The primary benefit of using a dedicated IP is that the reputation of that IP is based only on the mail you are sending. Shared IPs, on the other hand, have many users sending, so their reputation is based on all of the email from many users. A dedicated IP also means that your mail comes from a specific IP. When using shared IPs, the IP used will rotate and not always be the same. Poor list management, unsolicited emails, or unengaged recipients will cause issues on both shared and dedicated IPsa dedicated IP is never guaranteed to solve delivery problems.

If you are not sending a lot of email, a dedicated IP can hurt your deliverability because receiving servers are not seeing enough email to know whether to trust the IP or not. So each time you send anemail, they are re-evaluating every aspect of the email as though it's a new IP rather than one that isestablished and reliably sending email.

In our experience, you should be sending at least 5000 emails per day, at least three days per week to justify a dedicated IP. A single dedicated IP can handle up to 500,000 emails per day (distributed throughout the day). Some ISPs limit how much mail they will accept from individual IPs, per hour or day. Because of this, if your list is concentrated in certain ISPs, the amount of email you can send from a single IP may be lower.

If you are sending to a lot of corporate domains that need to be able towhitelist the IP you are sending from, a dedicated IP can be a really good option. It makes it easier for your clients or users with those corporate domains to whitelist just your IP instead of all of Mandrill's shared IPs.

If you are planning to send morein the future, beginning the warmup process for a dedicated IP can be beneficial. Just be sure thatyou do not spend time warming up the IP, and then leave it dormant for awhile; consistency in sending behavior is beneficial when it comes to warming up IPs. Mandrill has an automated warmup option that you can enable when you request the IP (or any timeafter the IP is provisioned).

Setting up reverse DNS lets you white label the domain name associated with your dedicated IP address.

Before getting started, you must set up an A record pointing your subdomain to your dedicated IP address. The domain should be a subdomain (like mail.yourdomain.com) and can't be a root domain (like yourdomain.com).

You can also manage custom DNS settings through the Mandrill API using the Ips calls.

Add Reverse DNS Settings in Mandrill

Go to theAdd-Onspage.

Click Configure reverse DNS under your dedicated IP address.

Enter your subdomain and clickCheck Settings.

In the modal window, click Add Reverse DNS.

The reverse DNS setup process takes about 24 hours, as Mandrill needs to configure a PTR record mapping your dedicated IP address back to the domain name. Many ISPs verify the TTL on PTR records and may reject the email based on their spam filtering heuristics if the TTL is less than 24 hours.

If you have more than one dedicated IP, Mandrill will send the rest of your mail over your other dedicated IPs during the reverse DNS set up phase. If you have only one dedicated IP, Mandrill will send the rest of your mail over our shared pool of IPs during that time.

Edit reverse DNS

Go to the Add-Ons page.

Click edit under your dedicated IP address.

Make any necessary changes, and then click the Check Settings button.

In the modal window, click Add Reverse DNS.

Remove reverse DNS

If you no longer want to white label the domain name tied to your dedicated IP address, you can remove the reverse DNS settings in Mandrill. The domain name will revert backto the mandrillapp.com domain within 24 hours, during which timeyour email will send over our shared pool of IPs temporarily (or your other dedicated IPs if you have more than one).

Go to the Add-Ons page.

Click the remove reverse dns link under your dedicated IP address.

Click the Remove reverse DNS button to confirm.

Mandrill supports conditional merge tags. Because Mandrill doesnot store list data, all merge tag values need to be provided in the API call or SMTP headers, and the conditions would be checking against those values.

Conditional merge tags support traditional IF, ELSE, and ELSEIF logic and IFNOT negative conditions.

Examples

Basic IF and ELSE conditions

Use IF conditions to display content only when the condition evaluates as true.

*|IF:MERGE|*

content to display if a value for MERGE is provided

*|END:IF|*

*|IF:MERGE=x|*

content to display if the value for MERGE is x

*|END:IF|*

When using a condition like *|IF:MERGE=x|*, and no value for MERGE is provided, the condition will evaluate as false.

Use IF and ELSE conditions to display content when a condition is true, but alternate content when the condition evaluates as false.

*|IF:MERGE|*

content to display

*|ELSE:|*

alternative content

*|END:IF|*

The ELSEIF condition

Use ELSEIF to display one of several options. Only the content following the first condition evaluated as true displayit will skip other conditions.

*|IF:MERGE=x|*

<p>content to display if the value for MERGE is x</p>

*|ELSEIF:MERGE=y|*

<p>content to display if the value for MERGE is not x, but is y</p>

*|ELSEIF:MERGE=z|*

<p>content to display if the value for MERGE is not x or y, but is z</p>

*|ELSE:|*

<p>alternate content to display if the value for MERGE is not x, y, or z</p>

*|END:IF|*

Nested conditions

*|IF:MERGE1=x|*

*|IF:MERGE2=y|*

<div mc:edit="main">

<p>content to display if both conditions are true</p>

</div>

*|END:IF|*

*|END:IF|*

Negative conditions

*|IF:MERGE!=x|*

content to display if the value for MERGE is not x

*|ELSE:|*

content to display if the value for MERGE is x

*|END:IF|*

*|IFNOT:MERGE|*

content to display if MERGE is not provided

*|ELSE:|*

content to display if MERGE is provided

*|END:IF|*

Yes. By default, for HTML messages, click-tracking applies to all links are in <a> tags.To disable click-tracking on individual links, add a new parameter to the link tag, mc:disable-tracking.

The HTML link looks similar to this example:

<a href="http://linkthatshouldnotbetracked.com" mc:disable-tracking>Click here to confirm your email address</a>

The extra parameter is removed when the email is sentand no click-tracking is applied to this link.

Mandrill adds a small, 1px by 1px graphic at the bottom of your HTML emails. When a recipient downloads images in your email, Mandrill will record this as an open.

If you have enabled click-tracking for your emails, Mandrill can also record an open when a recipient clicks on a Mandrill-tracked link. Since it is impossible to embed the tracking image in text-only emails, recipient clicks are the only way to track opens for text emails.

Enable open tracking

You can enable open tracking using the track_opens parameter (API), X-MC-Track (SMTP), or globally for your account on the Sending Options page.

Global settings apply for all emails by default, but if the API call or SMTP headers have different tracking options, this will override the account setting.

Yes. Mandrill processes bounces automatically and records that information in your account, but you can also receive bounce notifications via email. We'll parse the bounce message, generate a report, and send it to you via email automatically.

Bouncenotifications are onlysentto your bounce forwarding address. You will not receive emails for rejects, unsubscribes, or spam complaints. Set up webhooks to receive details about these events in your own application.

To set up a bounce forwarding address, follow these steps.

Go to the Sending Options page.

Enter your email address under Forward Bounce Notifications To This Address.

Click Save.

You can change the email address that receives bounce notifications up to three times in one day.

Bounces are undeliverable emails. They are usually separated into two categories: hard bounces and soft bounces.

Mandrill uses a specific set of heuristics to determine whether a bounce should be classified as hard or soft. Typically, permanent errors like non-existent mailboxes are classified as hard bounces, while quota errors and other temporary issues are treated as soft bounces.

Mandrill handles bounces and reports them automatically in your account.

Learn more about how Mandrill handles bounces.

Learn how to view bounce details in Mandrill.

A spam complaint occurs when a recipient clicks on the report spam button in their email program. If their ISP has a Feedback Loop (FBL), that action passes back to Mandrill,the recipientismoved to the Rejection Blacklist, and will no longer receive messages from you.

Spam complaints donot occur when an ISP has filtered an email to the spam or junk folder automatically. If the ISP does not provide a Feedback Loop, the complaint will not be recorded in your account, but future emails from you may be sent to the spam folder from that point forward unless the recipient takes action to remove the email from the spam folder.

Mandrill also tracks direct complaints. A direct complaint occurs when a recipient contacts Mandrill's abuse department, directly reporting an email as spam. Direct complaints are considered very serious as the recipient has gone to great lengths to reach out to Mandrill and report a message as unwanted or unsolicited.

Yes, Mandrill provides an easy-to-use merge tag to automatically add an unsubscribe link to your Mandrill emails. The merge tag consists of the word UNSUB, followed by a colon, and then a full website address (with http:// or https://) where recipients are redirected when the unsubscribe is processed:

*|UNSUB:http://mywebsite.com/unsub|*

If a recipient clicks the generated link, the message status changes to Unsubscribed and the recipient's address is added to the Rejection Blacklist in your Mandrill account. The redirect URL will be appended to include two query string parameters that can be used for processing the unsubscribe in your own system or database:

md_id: The _id, as provided in the API call and webhooks of the specific message where the unsubscribe link was clicked

md_email: AURL-encoded version of the recipient's email address

Using the unsub merge tag

The unsubscribe merge tag generates only the URL to unsubscribe and can be used in both HTML and text emails. In HTML, you might construct the link like this to create a clickable link for recipients to unsubscribe:

<a href="*|UNSUB:http://mywebsite.com/unsub|*">Click here to unsubscribe.</a>

Add an Email to the Rejection Blacklist

To add emails to the Rejection Blacklist, follow these steps.

Go to the Rejection Blacklistpage in your Mandrill account.

Click the Add to Blacklist button. Read more about rejected emails

Select Manually Add Addresses to add one email address per line in the provided text field, or choose Import Addresses From File to add multiple addresses at once by uploading a file (you must choose a plain text file with one email address per line).

Add a reason for the rejection in the field under the Note heading.

If you need to add the emails to a subaccount's Rejection Blacklist, choose the subaccount ID from the Add To This Subaccount's Blacklist drop-down menu.

Click Add to Blacklist.

Emails can also be added to a main account or subaccount's Rejection Blacklist via the Mandrill API.

Remove a Custom Entry from the Rejection Blacklist

Custom rejections never expire and adding and removing custom rejections won't affect your account's reputation. To remove an email from the Rejection Blacklist, click the remove link next to the entry in the list.

Emails can also be removed from the Rejection Blacklist via the Mandrill API. Emails added to the Rejection Blacklist automatically as the result of a bounce, unsubscribe, or spam complaint can be removed one at a time for a small reputation hit. .

After a bounce occurs for a recipient email address, Mandrill stops attempting delivery of the email. Further email to that address will be rejected temporarily.

Mandrill uses a set of heuristics to determine whether a bounce should be classified as a soft or hard bounce. Permanent errors such as invalid mailboxes will get classified as hard bounces, while quota errors and other temporary problems are treated as soft bounces. Hard bounce rejections last longer than soft bounce rejections, and Mandrill doesnot automatically convert soft bounces to hard bounces. If you are seeing a lot of soft bounces to an address, it may be a sign that the address is unusable.

View the Rejection Blacklist

Go to the Settings page in your Mandrill account.

Select Rejection Blacklist to view a list of addresses that have been added to the rejection list.

You can also view the Rejection Blacklist for a subaccount.

In addition to the email address, you will see the following items:

The reason the email address was added to the blacklist

Which sender the rejection applies to

The date the rejection expires

After the rejection expires, the email address remains on the list for reference, but email sent to that address will be attempted again instead of being rejected.

Rejections shouldnotbe removed in bulk, but if you know that a bounce was temporary or you have resolved an issue with the receiving server, you can remove individual rejections for a small hit to your account's reputation.

Mandrill automatically adds emails that have previously bounced, unsubscribed, or reported a message a spam to the Rejection Blacklist in your account, but you can also manually add addresses to the Rejection Blacklist. For example, a recipient may have contacted you directly and asked to be removed or you might want totest rejections using your own email address.

Custom rejections never expire and adding and removing custom rejections will not affect your account's reputation.

Learn how to add an email address to the Rejection Blacklist in your account.

Activity for your Mandrill account canbe exported from the Outbound Activity page or via the Mandrill API exports/activity call.

ExportActivity

If you only use the filters and drop-downselections, you can download the most recent 1,000 delivered and undelivered messages, or the entire results set. If you use a search term, up to 1,000 delivered and undelivered results may be exported.

Go to the Outbound Activity page in your Mandrill account.

Select any filters, such as date range, tag, sender and delivery status.

Click Export Results.

If you used a search term, a file will be downloaded immediately with the last 1,000 delivered and 1,000 undelivered messages matching the search term(s) and selected filters.

If no search terms were used, a drop-downdisplays with the export options. If you export the latest 1000 results, a file downloads immediately. If you select the option to Export all results, the export will be queued.

Queued Exports

For queued exports, an email is sentto the contact email address for the account when the export is ready for download. You may also go to theExportspage to view exports for your account. Export download links expire after 7 days. The export displays in the exports list for an additional 7 days for record-keeping purposes.

Mandrill tracks emails on a per-message basis, so opens, clicks and delivery data are tracked for individual emails sent through your account. You can add tags and metadata to give further context to the emails you send.

Mandrill automatically indexes a number of fields that you can use to search or find interesting trends relevant to your sending. Searching is available in the web application and via the API.

Date Ranges

Before you get started, it's important to note how long messages are searchable in Mandrill. Detailed information for delivered messages is stored for 30 days, while bounced message data is kept for 90 days for record-keeping purposes. Stats for the account and tag-based stats are stored indefinitely. Overall stats can be viewed on the Dashboard of your Mandrill account or using the senders, tags, and templates API calls.

Query Syntax

Mandrill searches utilize Lucene queries, and by default we search all indexed fields for your search terms (unless a field is specified).

From the Lucene documentation:

A query is broken up into terms and operators. There are two types of terms: Single Terms and Phrases.

A Single Term is a single word such as "test" or "hello".

A Phrase is a group of words surrounded by double quotes such as "hello dolly".

Multiple terms can be combined togetherwith Boolean operators to form a more complex query.

Mandrill supports all of the boolean operators like AND, OR, and NOT, along with wildcards (* for multiple character and? for single-character wildcardsjust do not start a search with a wildcard).

If you want to search a specific field for something, use the field name followed by a colon and then your search term or phrase. The following fields are indexed by Mandrill and can be used for searching message data:

Field Name

Description

state

Search by the status of the email. Options are 'sent', 'bounced', 'soft-bounced', 'rejected', 'spam', and 'unsub'

sender

Search the sender/from email address for the message

ts

Unix timestamp when the message was sent. Supports searching a range, such as ts:[START_TIME TO STOP_TIME] where START_TIME is the starting time, and STOP_TIME is the end time for the range.

full_email

Search the full email address for the recipient

email

A tokenized field for recipient email address

subject

The subject line of the message

tags

The tags applied to the message

opens.ts

Unix timestamp when the recipient opened the message. Supports searching a range, such as opens.ts:[START_TIME TO STOP_TIME] where START_TIME is the starting time, and STOP_TIME is the end time for the range.

opens.location

Search for the location where a recipient opened the message.

opens.ua

Search based on the user-agent detected for an open event. Value is 'null' if no user-agent is detected.

opens.ip

Search based on the IP address where an open originated.

clicks.ts

Unix timestamp when the recipient clicked a tracked URL in the message. Supports searching a range, such as clicks.ts:[START_TIME TO STOP_TIME] where START_TIME is the starting time, and STOP_TIME is the end time for the range.

clicks.location

Search for the location where a recipient clicked the message.

clicks.ua

Search based on the user-agent detected for a click event. Value is 'null' if no user-agent is detected.

clicks.ip

Search based on the IP address where a click originated.

url

Use to search for messages where the recipient clicked on a specific URL or URL pattern

u_metadatafield

Search your indexed [custom metadata](http://help.mandrill.com/entries/21786413-using-custom-message-metadata) field, where metadatafield is the name of the field.

subaccount

Search by the subaccount ID that sent the message. Supports wildcards.

smtp_events.ts

Unix timestamp when the SMTP event occurred. Supports searching a range, such as smtp_events.ts:[START_TIME TO STOP_TIME] where START_TIME is the starting time, and STOP_TIME is the end time for the range.

smtp_events.type

Search the event type. Options are 'sent' and 'deferred'.

smtp_events.diag

Search the SMTP diagnostic messages for a keyword or phrase.

smtp_events.source_ip

Search by the Mandrill source IP that sent the message.

smtp_events.destination_ip

Search the destination IP that Mandrill connected to in orderto deliver the message.

smtp_events.size

Search based on the size of the SMTP message in bytes. Supports searching a range such as smtp_events.size:[MINIMUM TO MAXIMUM] where MINIMUM is the starting time, and MAXIMUM is the end time for the range.

Examples

subject:welcome OR subject:bienvenidos

Searches messages that contain 'welcome' or 'bienvenidos' in the subject line

full_email:joe@domain.* AND sender:[email protected]

Searches for messages sent to recipients whose email addresses start with joe@domain (to capture, for example [email protected], [email protected] and [email protected]) that were also sent by [email protected]

email:gmail.com

Searches for all recipients with 'gmail.com' in the address. If you have a recipient with the address [email protected], that will also be included in this search, but this will generallyreturn all recipients for the gmail.com domain.

ts:[1349049600 TO 1349053200] AND subject:"Order Receipt" AND opens.ts:[1349049600 TO 1349056800]

Searches messages which were:

Sent between 1349049600 Unix Time (October 1, 2012, 00:00:00 GMT) and 1349053200 Unix Time (October 1, 2012, 01:00:00 GMT); and

That have a subject line that contains the phrase "Order Receipt"; and

Which were opened between 1349049600 Unix Time (October 1, 2012, 00:00:00 GMT) and 1349056800 (October 1, 2012, 02:00:00 GMT).

url:twitter.com OR url:facebook.com

Searches for messages where the recipients clicked URLs that start with either twitter.com or facebook.com

tags:Welcome AND tags:a_test

Searches for messages that are tagged with both 'Welcome' and 'a_test'

During reporting, Mandrill strips the query string from your links by default. This is normally what you want, as query strings should usually just be metadata and should notbe counted towards the uniqueness of a URL. However, some CMSes may not act this way, so the option to disable this behavior is included.

For example, these three links:

http://example.com/profile

http://example.com/profile?option_a=123&option_b=456

http://example.com/profile?option_b=456&option_a=123

Arereported as the same link:

http://example.com/profile

If this option is set to false, however, they would be tracked as three entirely separate links.

You can control whether or not to strip query strings from URLs using the url_strip_qs parameter (API), X-MC-URLStripQS (SMTP), or globally for your account on the Sending Options page.

Yes, you can any filetype (up to maximum total message size of 25MB). Messages that include attachments areprocessed through a series of virus scanning engines to make sure the attachments are safe for recipients.

Messages in Mandrill can not exceed 25MB in total size (including content and attachments). There is no specific limit for individual attachments, just the total size of the message. Because attachments are Base64-encoded, this means that they will be 1/3 larger when sending than they are on disk because of the encoding.

Mandrill does not store yourimages, but there are a few ways to include them in your emails. Below are some tips to help you get started.

Upload images to a publicly-accessible server or a reputable image hosting service. Then, link to the image URL in your message HTML or template :

<img src="http://photosite.com/image.jpg" alt="My image" />

You can also use merge tags to insert image names dynamically:

<img src="http://photosite.com/*|IMAGENAME|*" alt="My image" />

We recommend that you host your images on your own site instead ofgeneral sharing services. File and photo hosting sites could have other users' content on them and are more likely to be flagged by spam filters, be on blacklists, or cause failed content reviews for your Mandrill account.

Include images as inline attachments with your API calls using the images parameter. You must provide the image name (Content-ID), the content (as a base64 encoded string), and the image MIME type. Reference the image name in the 'src' in your HTML content:

<img src="cid:image_name">

For most SMTP libraries, including inline images is handled automatically. For example, if you insert an image inline, an img tag is added which then references the Content-ID of the image that's attached. How to add inline images will depend on the SMTP library being used.

Including inline images causes emails to be much larger since attachments are base64-encoded. This also means more data is being transferred to Mandrill, and more data is also being sent to receiving servers. If you are using the same images often or sending in bulk, hosting those images and referencing them in your HTML is more efficient.

You cannot upload images to templates or store them in Mandrill.

For each email you send, Mandrill automatically tracks and records the SMTP response we receive from recipient mail servers. Some successfully delivered emails will include a "queued" notation in the SMTP response such as 250 OK; queued as 12345. This indicates that the email wasdelivered to the recipient as expected, but may require additional processing before it lands in the recipient's mailbox.

For example, most times Mandrill can send email much faster than recipient servers can accept or process it. Most times, things like the time of day and overall email traffic to that ISP or recipient server can affect how quickly they can receive and process your email.

Email clients typically support only a subset of valid HTML and do not have strong support for CSS (especially CSS in the <head> of the HTML email). Yahoo, Outlook, and even Gmail strip the CSS included in the <head> of your HTML. In most cases, CSS for emailis handled using inline styles.

Rather than inlining your CSS manually before sending your HTML to Mandrill or when you generate a template, we offer a sending option to inline CSS automatically at the time of send (as long as your message is 256KB or smaller). Set this on the Sending Defaults page in your Mandrill account, on a per-message basis using the inline_css option (API) or X-MC-InlineCSS header (SMTP), or using the Mandrill Rules Engine.

CSS inlining can be an intensive process and because Mandrill is designed to get your emails out as quickly as possible, the extra processing time to inline CSS can affect delivery speeds. If you have a larger template or HTML document, we recommend that you inline your styles manually or use the CSS Inliner Tool as a part of your sending process.

Mandrill will inline CSS only for HTML emails smaller than 256KB.

Mandrill serves users throughout the world, and different laws govern email in various countries. Consult with a professional in your area about what laws or regulations apply to the emails you are sending. Failure to comply with the rules governing the email you are sending can cause legal consequences, such as fines of hundreds of dollars per recipient.

In the United States, it is important to know and understand U.S. CAN-SPAM Act rules. This includes a requirement for an unsubscribe link or process and a physical contact address. Refer to the CAN-SPAM Act: A Compliance Guide for Business about the rules and when they apply.

International Requirements By Country

If you're in another country, refer to the resources below to understand more about the anti-spam legislation in countries outside of the US.

Canada- C-28

Canadas Anti-Spam Legislation (CASL) amends the Canadian Radio-television and Telecommunications Commission Act, the Competition Act, the Personal Information Protection and Electronic Documents Act and the Telecommunications Act. It is very similar to CAN-SPAM, but has some minor differences and covers all electronic messages, not just email.

Australia

Spam Act 2003, Act No. 129 of 2003 as amended.

EU

Article 13 of DIRECTIVE 2002/58/EC OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL of 12 July 2002 concerning the processing of personal data and the protection of privacy in the electronic communications sector (Directive on privacy and electronic communications).

The EU body that addresses spam is The Contact Network of Spam Enforcement Authorities (CNSA).

Each member state the implements the Directiveindependently, so check your country laws for more details.

UK

The Privacy and Electronic Communications (EC Directive) Regulations

Austria

Telecommunications Act 2003

Belgium

Commission de la protection de la vie prive, Le spam en Belgique Etat des lieux en juillet 2003, July 4, 2003

Cyprus

Section 06 of the Regulation of Electronic Communications and Postal Services Law of 2004 (Law 12 (I) / 2004 deals with unsolicited communications (spam)

Czech Republic

Act No. 480/2004 Coll., on Certain Information Society Services

Estonia

Information Society Service Act

France

Falls under the Commission Nationale de l'Informatique et des Liberts (CNIL) [National Data Processing and Liberties Commission], Electronic Mailing and Data Protection (Oct. 14, 1999) (French) CNIL Guidelines on email marketing.

Germany

Art. 7 German Unfair Competition Law (Gesetz gegen Unlauteren Wettbewerb) (UWG)

Art. 202a, 263, 303a, 303b of the German Criminal Code Art. 6 of the German Law regarding Information Society Services Art. 28 Par. 4 of the German Data Protection Act

Italy

Italy's anti-spam laws are very strict. You can even be imprisoned for sending spam. If you're sending to Italian recipients, you'd want to follow these guidelinesas well.

Personal Data Protection Code (legislative decree no. 196/2003)

The Code transposed EC Directive 95/46 on the protection of personal data and EC Directive 2002/58 on privacy in electronic communications; it consolidated all Italian pre-existing laws and regulations in this sector.

DL 196/2003 Personal Data Protection Code DL 675/1996 on privacy protection states, inter alia, that a company must have authorization from each user whose personal data (such as e-mail) they want to use. DL 171/1998 (deriving from the European Community directive 97/66/CE) on telecommunications privacy protection: this put outlaws all automatic systems to call a user and says that all the expenses of an advertising must be paid by the company and not the user (faxes and e-mails are instead paid also by the user).

DL 185/1999 (deriving from the European Community directive 97/7/CE) on customer protection with respect to long-distance contracts: this obliges companies to seek the permission of the user for virtual or telephone sales.

Netherlands

Article 11.7 of the Dutch Telecommunications Act and Dutch Data Protection Act.

Sweden

Swedish Marketing Act (Swedish Code of Statutes, SFS 1995:450).

Personal Data Act (Swedish Code of Statutes, SFS 1998:204), in so far as spam activities involve processing of personal data.

Mandrill allows you to attach custom, individualized metadata to messages. Use custom metadata to integrate your application's data model with Mandrill. Metadata is searchable (either in the activity view or via the API) and is included with webhook events and activity CSV exports.

Metadata Format

The metadata format differs slightly depending on whether you are using SMTP or the API to send your messages. Key names should include only alphanumeric characters and underscores, and names may not start with an underscore. Field names can contain spaces, but Mandrill does not support searching for field names with spaces or non-alphanumeric characters.

Regardless of how you send your message, the following rules apply:

For each message, metadatais limited to 200 bytes of JSON-encoded data.

Nested data structures are not supported.

Values should be limited to scalar types (numbers, strings, boolean values, and null).

SMTP

To include custom metadata with an SMTP submission, include the X-MC-Metadata header with a JSON-encoded set of key-value pairs as the value. For example:

X-MC-Metadata: { "user_id": "45829", "location_id": "111" }

API

Using the messages/send.json or messages/send-template.json endpoint, include metadata as part of the message parameter:

{

"key": "example key",

"message": {

"html": "example html",

"subject": "example subject",

"from_email": "[email protected]",

"to": [

{

"email": "recipient_email",

"name": "recipient_name"

}

],

"metadata": {

"user_id": "45829",

"location_id": "111"

}

}

}

Global and Per-Recipient Metadata

The previous examples add metadata for all recipients of the message. If your message has many recipients and you want to individualize the metadata for each recipient, you can include recipient-specific metadata.

SMTP

Include a _rcpt key in the encoded JSON object to designate which recipient the metadata should apply to. Metadata that does not specify a recipient is applied globally to all recipients of the message, and per-recipient keys take precedence over global keys with the same name.

API

Use the recipient_metadata parameter to designate the recipient and their corresponding values. Per-recipient keys take precedence over global keys with the same name.

Examples

For example, consider the headers for the following message, with three recipients ([email protected], [email protected], and [email protected]):

X-MC-Metadata: { "group_id": "users_active" }

X-MC-Metadata: { "_rcpt": "[email protected]", "user_id": "123" }

X-MC-Metadata: { "_rcpt": "[email protected]", "user_id": "456" }

Or the following specified via an API call:

...

"metadata": {

"group_id": "users_active"

},

"recipient_metadata": [

{

"rcpt": "[email protected]",

"values": {

"user_id": "123"

}

},

{

"rcpt": "[email protected]",

"values": {

"user_id": "456"

}

}

]

...

The following metadata will be stored. Because the global metadata does not include auser_id field and no per-recipient metadata was defined for [email protected], that recipient's metadata doesn't have a value for the user_id field:

Recipientgroup_iduser_id

[email protected] users_active 123

[email protected] users_active 456

[email protected] users_active null

When merging global metadata with per-recipient metadata, each recipient's final, merged metadata must still be below the 200-byte encoded size limit. If a recipient's merged metadata exceeds this limit, the metadata for that recipient will be discarded.

Configure Metadata Fields

By default, message metadata is included with webhook calls but NOT included in your search index. To enable searching and reporting on metadata, you must tell Mandrill which keys to add to its search index. You can do this on the Custom Metadata settings page.

When you add or remove a custom metadata field, the change will take effect immediately for new messages, and Mandrill will process your previously-sent messagesto apply the change to them. Depending on the size of your account, this can take some time.

Search Metadata

You can search your indexed metadata fields, either in the Outgoing Activity in your account or via the API's messages/search call. To search for an indexed field, prefix the metadata field name with u_ in your search query:

full_email:[email protected] AND u_order_id:1398274

If the metadata value that you are searching for includes non-alphanumeric characters, surround it in quotes:

full_email:[email protected] AND u_contact_url:"http://example.com/test"

View Metadata

Mandrill automatically displaysindexed metadata fields on the Outbound Activity page. You can also configure each custom field with a unique Mustache template to control how the metadata renders in your activity log.

For example, if you are using Mandrill to send signup confirmation messages, and you include a unique user identifier in each message's metadata, you could use the following view template to transform the user id field into a link to the user's profile page in your application:

<a href="http://yourapplication.com/user/{{value}}">{{value}}</a>

You can reference other custom metadata fields by prefixing their names with metadata. If you configured theusername and user_id fields,you could change the template in the previous example to include the username as the text of the link:

<a href="http://yourapplication.com/user/{{metadata.user_id}}">{{metadata.username}}</a>

These properties are also available in metadata view templates for all messages:

name: the current field's name

value: the current field's value

email: the message recipient's email address

subject: the messages subject

You can always test templates via the Mandrill API or SMTP Integration, but you can also send a quick test email directly from your Mandrill account following the steps below.

Things to know

Here are some things to know before you begin this process.

Test emails are billed just like all other emails sent from your Mandrill account.

Any sending options enabled for your account will also be applied to test emails.

If you've met your hourly quota, the test email will be queued just like other messages and will be sent the next hour.

Send a test email

Go to Outbound in your Mandrill account.

Click Templates.

Hover over the template, and then click edit code.

ClickSend Test.

Type an email address, and then click Send Test.

If you have not set a default subject line for the template, Mandrill automatically sets the test email subject to [TEST] Template Name Template Test where "Template Name" is replaced with the actual name you provided for the template.

Mandrill automatically tags these messages with template-test so you can search and filter your Outbound Activity based on these tests.

To create a new rule in your Mandrill account, follow these steps.

Go to Outbound, and then choose Rules.

ClickAdd Rule.

Add a descriptive name for your rule.

Set the trigger for your rule and set your if/then condition(s).

Click Submit.

Learn more about Mandrill's rules engine and view example rules.

Mandrill also shows the approximate number of emails you sent in the past seven days (7) that match the criteria before you save a new rule. Rules will not affect messages alreadysent.

Note: If you haveset up a rule that uses pure wildcards, leading wildcards, or null values, the number of matched emails Mandrill can detect in the last 7 days may be skewed.

Searching when setting up a rule uses a slightly different query syntax than when you actuallysend anemail. For searching past activity, pure wildcard searches or wildcards at the beginning of a search are notsupported (ex: *@domain.com).

After you create a Mandrill account, you can find your SMTP credentials on the SMTP & API Info page.

The SMTP password is any active API key for your account,not the password used to log in to Mandrill. The credentials list port 587, but any port supported by Mandrill will work, and there is no configuration change needed within Mandrill to activate one of the alternate ports.

Use port 25, 587, or 2525 if you are not encrypting the communication between your system and Mandrill or if you want to use the STARTTLS extension (also known as TLS encryption). SSL is supported on port 465.

Note that ISPs may redirect traffic on certain ports, so you can decide which port you use.

Yes, you can use SSL on port 465 for sending through Mandrill. We also support the STARTTLS extension (also known as TLS) for encryption on port25, 587, or 2525.

If you have a dedicated IP, you can instruct your clients or recipients to whitelist just that IP. If you do not have a dedicated IP, your emails will be sent from Mandrill's shared IP range. This range is continuously updated as we add more servers for sending.

We do not recommend whitelisting by IP because Mandrill's shared IPs may change without notice and the recipient would be whitelisting all mail from Mandrill. If whitelisting by IP is the only option, the recipient domain should check for the most up-to-date IP information in the TXT record for spf.mandrillapp.com. On a Mac or Linux, use the following command to get this information:

dig TXT spf.mandrillapp.com

The recordis updated whennew IPsare added to Mandrill's sending IP range. If a receiving server is whitelisting the range, we recommended periodic checksto ensure they have the current range used by Mandrill.

When Mandrill sends an email, the recipient's mail server provides a response when the message is accepted for delivery, when it bounces, or when it can't be delivered for any reason. Mandrill stores these SMTP responses for you automatically.

If an email is accepted for delivery by a recipient mail server, Mandrill does not have any additional insight into what happens to the message from that point. For example, the message may go through a series of spam filters or other processes that aren't disclosed to senders. You can also enable open and click tracking for additional confirmation on the status of an email delivered by Mandrill.

View SMTP Responses in Mandrill

Go to Outbound.

Choose Activity.

Filter your activity by Delivered emails, Hard Bounces, Soft-Bounces, or search for a recipient email address manually.

Click the message status link to view the full SMTP response. Rejected

We'll also show you the originating IP address, the IP address for the mail host that accepted the email, as well as the size of the sent message.

You can also view the response(s) via our API and webhooks in the smtp_events array.

Common SMTP Responses

SMTP replies vary based on the server or ISP that issues them, though there are some general guidelines. Each response will include (at the very least) a three-digit code. The first digit typically indicates whether the server was able to accept the message or not. For example:

2: A response that begins with a '2' generally means that the message was accepted without error.

4: Responses that start with '4' typically indicate a temporary error. We'll usually retry delivery on these.

5: Responses with a '5' at the beginning of the code usually indicate a soft bounce or a hard bounce.

The second and third digits can provide additional info, but are usually highly-contextual and specific to the particular mail server.

emails won't include SMTP events as these messages aren't sent.

The Return-Path header shows where smtp events and bounce messages should be sent. By default, this address points to mandrillapp.com, but you can customize the address to point to your own domain instead.

Even if you use a custom Return Path domain,Mandrill still handles the bounces. If you need to receive bounce details in your own application or to a specific email address, you can set up webhooks and Mandrill will send information to your webhook URL when these events occur. From there, you can process the events as needed in your application/database or use code to forward the bounce information along in a new email.

Add a Custom Return Path Domain

Before getting started, set up a CNAME record pointing your subdomain to mandrillapp.com.The domain must be a subdomain (like mail.yourdomain.com) and can not be a root domain (like yourdomain.com). You can use anyvalid tracking domain asa Return Path domain, but we suggest creating a unique subdomain specifically for this purpose.

Save the Return Path Domain in Mandrill

Go to Settings.

Choose Tracking & Return Path Domains, enter your subdomain, and then click Add.

Click Test DNS Settings to verify the settings for the subdomain you added.

Enable a Custom Return Path Domain

You can enable a custom return path domain on a per-message basis using the return_path_domain parameter (API), X-MC-ReturnPathDomain (SMTP), or globally for your account under on the Sending Defaults page.Global account settings apply for all emails by default, but if the API call or SMTP headers have different tracking options, this will override the default account setting.

Notes

Each DNS provider/host may handle adding or editing records differently, so your host's technical support or documentation is the best resource for any limitations or formatting specific to that provider.

Some DNS providers take longer than others to publish and push the record. If you are adding a new record, those often validate in several minutes. Changing records can take longer, but can vary based on your DNS provider and TTL for the record.

You can only add aReturn Path domain to one Mandrill account. Additions to a different Mandrill account will result in an error. If you have a specific use-case for a Return Path domain being used across multiple Mandrill accounts, contact Mandrill support.

Need help? Choose one of our support optionsto get answers to your questions about your Mandrill account.

Email

Email support isavailable Monday - Friday between 9am and 5pm EST. Click on the Support link at the bottom of any page to submit your request.

Documentation

Mandrill Knowledgebase

MandrillAPI documentation

Official API Clients

You can view allof the Mandrill API clients on Bitbucket or check out the language-specific repositories below. You can also view sample API requests and test each endpoint right in your browser using our official API docs.

Mandrill has official API clients/wrappers for the following languages:

Ruby

http://rubygems.org/gems/mandrill-api

Python

http://pypi.python.org/pypi/mandrill/

NodeJS

https://npmjs.org/package/mandrill-api

PHP

http://packagist.org/packages/mandrill/mandrill

JavaScript

https://bitbucket.org/mailchimp/mandrill-api-js

Third-Party API Wrappers

Here's a list of known Mandrill API wrappers created by third parties. Contact each wrapper's developer for detailed information:

Ruby

https://github.com/evendis/mandrill-rails (Rails)

Python/Django

https://github.com/michaelhelmick/python-mailsnake

https://github.com/brack3t/Djrill

https://github.com/jpadilla/mandrill-inbound-python

PHP

https://github.com/kai5263499/mandrill-php

https://github.com/darrenscerri/Mindrill

https://github.com/MichMich/laravel-mandrill (Laravel)

https://github.com/eoko/zf-mandrill (Zend)

https://packagist.org/packages/accord/mandrill-swiftmailer-bundle (Symfony)

.NET

http://mandrillapiwrapper.codeplex.com (C#)

http://mcapinet.codeplex.com (C#, VB)

https://github.com/shawnmclean/Mandrill-dotnet

https://github.com/feinoujc/Mandrill.net

Java

https://github.com/cribbstechnologies/Java-Mandrill-Wrapper

https://github.com/rschreijer/lutung

NodeJS

https://github.com/jimrubenstein/node-mandrill

https://github.com/rschmukler/powerdrill

Note

You need to add SPF and DKIM records and verify ownership of your sending domains before you can send email through your account. Mandrill will not send emails from unverified domains or domains without valid SPF and DKIM records, including public domains like gmail.com, yahoo.com, and more.

A message that is rejected with the reject reason unsigned indicates that the sending domain has not been properly set up, and that your account cannot send and authenticate email from that domain.

Learn more about SPF and DKIM and domain verification, or manage sending domains in your Mandrill account.

Yes. By default, Mandrill only includes the List-Unsubscribe header if you also include our automatic unsubscribe link in your email. If you manage your own unsubscribe process, you can provide your own List-Unsubscribe header in your SMTP message or API call instead.

Learn more about how recipients can unsubscribe from Mandrill emails.