Mailchimp Developer Homepage

SMTP Integration

The basics

Mailchimp Transactional allows you to send email via SMTP, which means you can easily integrate it into an existing SMTP library or framework. If you’re already sending transactional emails for your website through SMTP, you can typically change your SMTP configuration to use your Mailchimp Transactional credentials and begin sending immediately. 

Note: While SMTP offers the same sending capabilities as the Transactional API, the latter also lets you view or parse reporting data in your own app or system. If you’re trying to decide between sending with SMTP or with the API, you can read more about the two routes in Fundamentals.

anchor to credentials-and-configurationCredentials and configuration

After you’ve created a Mailchimp Transactional account, you can find your SMTP credentials on the SMTP & API Info page. 

The host for all accounts is smtp.mandrillapp.com.

You can use any active API key for your account as your SMTP password. Since the API key is sufficient for authentication, Mailchimp doesn’t use the SMTP username to authenticate your request, but we recommend using your Mailchimp account’s primary contact email as the username.

Use ports 25, 587, or 2525 for non-encrypted communication between your system and Mailchimp Transactional. You can also use the STARTTLS extension (also known as TLS encryption) on these ports. For secure SSL connections, use port 465.

There is no configuration change needed within Mailchimp Transactional to activate one of the alternate ports. ISPs may redirect traffic on certain ports, which might determine which port you need to use.

anchor to character-encodingCharacter encoding

Generally, SMTP is a 7-bit-only protocol, which means any non-ASCII characters need to be escaped for safe transport. Typically your SMTP library or application will handle this kind of encoding automatically, and you should not need to do anything. 

For example, to send the subject Mailchimp likes ASCII, but ❤ Unicode. over SMTP, your sending tools should encode the header according to RFC 2047 like this:

Subject: =?UTF-8?B?TWFuZHJpbGwgbGlrZXMgQVNDSUksIGJ1dCDinaQgVW5pY29kZS4=?=

Or like this:

Subject: Mailchimp likes ASCII, but =?UTF-8?Q?=E2=9D=A4?= Unicode.

For any non-ASCII characters in the body of your message (in either the text or HTML parts), escape those as well, using a Content-Transfer-Encoding like base64 or quoted-printable according to RFC 2045.

anchor to third-party-pluginsThird-party plugins

There are a number of third-party plugins and modules that allow you to route your site’s mail through Mailchimp Transactional; check with your CMS provider to see what they support. 

Some things to note when working with third-party products: 

  • Mailchimp Transactional was formerly known as Mandrill and may still be referred to as such by third-party plug-ins or apps.

  • Mailchimp Transactional does not create or maintain third-party plugins, and we can’t guarantee these services or products.

  • Before you send email through your account, you must add SPF and DKIM records and verify ownership of your sending domains. 

anchor to troubleshootingTroubleshooting

If you’re having trouble sending with SMTP, you can investigate your sends in the API logs.

If you’re just getting started, you might see “Relay Access Denied” or “Unable to Connect to Host” errors. A few things you can check: 

  • Make sure your hosting provider or ISP allows outbound SMTP connections. Some shared hosting providers only allow outbound SMTP connections on dedicated servers, while others block them completely. In some cases, hosting providers might redirect the connection, so instead of connecting to smtp.mandrillapp.com, you connect to their local server instead.

  • Make sure the port you’ve selected is one that your hosting provider or ISP has available for outbound SMTP connections. Some hosts block all connections on port 25, for example, so you can try using a different supported port.

  • Double check that you’re using a valid API key to connect via SMTP — not your password for Mailchimp Transactional’s web application.

  • If you’re using Postfix, make sure that you have an SASL library (like libsasl2 or cyrus) installed and up to date. Otherwise, you may be connecting but not passing authentication credentials.

  • For other SMTP libraries, make sure you’re using login or plain authentication methods.

Once you’ve confirmed all of the above, if you’re still seeing issues, enable additional logging in your SMTP program or library. If you’re using an integration, contact the integration developer for information on configuring logging of the SMTP conversation.

If you suspect you’re unable to connect to Mailchimp’s SMTP servers, you can try connecting manually using telnet on your server. For example, you can open a new connection to smtp.mandrillapp.com on any one of our supported ports (25, 587, 2525, or 465):

telnet smtp.mandrillapp.com 2525

If the connection is successful, you’ll see a response like this one:

Trying 54.204.208.115... Connected to smtp.us-east-1.mandrillapp.com. Escape character is '^]'. 220 smtp.mandrillapp.com ESMTP

You can also try pinging Mailchimp’s SMTP servers to test your connection status:

ping smtp.mandrillapp.com

Send via SMTP with your programming language of choice

Most likely, you’re developing your application using a framework or a set of third-party dependencies, and how you send via SMTP in your language of choice will vary depending on what your language or framework supports. 

Rather than document other languages and third-party tools, we recommend that you look at the documentation for your tools to find the best way to send email via SMTP in that ecosystem.

In general, however, to send via SMTP, you’ll need the following information, regardless of how your tools of choice are configured:

  • Address: smtp.mandrillapp.com

  • Port: 25, 587, 2525, or 465 (SSL)

  • Username: Any string (we recommend using the primary contact email on your Mailchimp account)

  • Password: Any valid Mailchimp Transactional API key 

Your tools may also require the following information:

  • Authentication type: login or plain

  • Domain: Your sending domain, e.g., mail.example.com

Customize messages with SMTP headers

You can use SMTP headers to customize your messages, add tracking, or specify options for Mailchimp Transactional to apply to your emails. How you set the headers is dependent upon your environment — read the documentation for your tools for more information on how to set SMTP headers.