Mandrill Getting Started: Initiate Transactional Email (2026)

Getting started overview

Mandrill functions as a transactional email API, integral to the Mailchimp ecosystem. It is designed for sending automated, event-triggered emails such as account notifications, password resets, and e-commerce confirmations. Access to Mandrill requires an active, paid Mailchimp account, as it is offered as an add-on service rather than a standalone product. The API supports various programming languages through official and community-contributed client libraries, facilitating integration into diverse application environments.

This guide provides a structured approach to initiating Mandrill: from account provisioning and API key generation to successfully sending your first email. It also covers common next steps for further integration and troubleshooting tips for initial setup issues.

Here is a quick reference table outlining the Mandrill getting started process:

Create an account and get keys

To begin using Mandrill, you must first have a paid Mailchimp account. Mandrill is not available as a standalone service. If you do not have a Mailchimp account, you will need to create one and subscribe to a paid plan. Once your Mailchimp account is active, you can add Mandrill as a transactional email add-on. Pricing for Mandrill starts at $20 for 25,000 emails per month, with costs scaling based on usage.

Account Setup

1. Create a Mailchimp Account: Navigate to the Mailchimp website and sign up or log in to an existing account.
2. Upgrade to a Paid Plan: Ensure your Mailchimp account is on a paid plan, as Mandrill requires this.
3. Add Mandrill: From your Mailchimp dashboard, locate the Mandrill add-on option and enable it. This will provision your Mandrill account.

Generating an API Key

API keys are essential for authenticating your requests to the Mandrill API. Each key is unique and should be treated as sensitive information, similar to a password.

1. Access Mandrill Dashboard: Once Mandrill is enabled, access its dedicated dashboard, typically found within your Mailchimp account navigation.
2. Navigate to API Keys: In the Mandrill dashboard, go to the Settings or API Keys section. The specific path is detailed in the Mandrill Getting Started API documentation.
3. Create New API Key: Click the button to generate a new API key. You may be prompted to provide a descriptive label for the key, which can help you manage multiple keys for different applications.
4. Record Your Key: Copy the generated API key immediately. Mandrill typically only displays the full key once, and you will not be able to retrieve it again if lost. Store it securely, preferably using environment variables or a secrets management service in your application.

Mandrill API keys are used in the key parameter for most API calls or as the password when using SMTP. For example, when making an API call, it might look like {"key": "YOUR_MANDRILL_API_KEY", "message": {...}}.

Your first request

To send your first email with Mandrill, you will need to verify a sending domain and then construct an API call. Mandrill supports both a RESTful API and an SMTP interface for sending emails. For this guide, we will focus on the API method.

Verify Your Sending Domain

Before sending emails, Mandrill requires you to verify ownership of your sending domain to prevent spam and ensure deliverability. This involves adding DNS records (TXT and CNAME) to your domain's DNS configuration.

1. Add a Domain: In your Mandrill dashboard, navigate to Settings > Sending Domains and add the domain you wish to send emails from (e.g., yourcompany.com).
2. Configure DNS Records: Mandrill will provide specific TXT and CNAME records. You will need to add these records to your domain's DNS provider. The TXT record verifies domain ownership, while the CNAME record handles tracking and authentication (DKIM/SPF). Refer to your domain registrar's documentation for how to add DNS records.
3. Verify Domain: Once the DNS records have propagated (which can take a few minutes to several hours), return to the Mandrill dashboard and click the 'Verify' button next to your domain.

Sending an Email via API (Example using curl)

The Mandrill API is accessed via HTTPS POST requests to https://mandrillapp.com/api/1.0/messages/send.json. This example demonstrates a basic email send using curl, which can be adapted for any programming language.

curl -A 'Mandrill-Curl/1.0' -d '{"key": "YOUR_MANDRILL_API_KEY", "message": {"from_email": "[email protected]", "to": [{"email": "[email protected]", "type": "to"}], "subject": "Your First Mandrill Email", "html": "<p>Hello from Mandrill!</p>"}}' https://mandrillapp.com/api/1.0/messages/send.json

Replace YOUR_MANDRILL_API_KEY with your actual Mandrill API key, [email protected] with an email address from your verified domain, and [email protected] with the intended recipient's email address. The html field can contain the full HTML content of your email.

Using an SDK

Mandrill provides official and community-supported client libraries for various languages, simplifying API interactions. For example, using the Python SDK:

import mandrill

try:
    mandrill_client = mandrill.Mandrill('YOUR_MANDRILL_API_KEY')
    message = {
        'from_email': '[email protected]',
        'to': [{'email': '[email protected]', 'type': 'to'}],
        'subject': 'Your First Mandrill Email (Python SDK)',
        'html': '<p>Hello from Mandrill via Python SDK!</p>',
    }
    result = mandrill_client.messages.send(message=message, async=False)
    print(result)
except mandrill.Error as e:
    # Mandrill errors are thrown as exceptions
    print('A Mandrill error occurred: %s - %s' % (e.__class__, e))

Install the Python SDK using pip install python-mandrill. Similar SDKs exist for PHP, Ruby, Node.js, Go, C#, and Java, each abstracting the HTTP request details.

Common next steps

After successfully sending your first email, consider these steps to enhance your Mandrill integration:

• Implement Webhooks: Configure webhooks to receive real-time notifications about email events such as opens, clicks, bounces, and complaints. This is crucial for tracking email performance and automating workflows. Mandrill's webhook documentation provides details on setup and payload structures.
• Utilize Templates: Instead of sending raw HTML, create and manage email templates directly within the Mandrill dashboard. This allows for easier content management, A/B testing, and dynamic content injection using merge tags.
• Advanced Sending Options: Explore features like scheduled sends, tags for analytics, subaccounts for organizational purposes, and IP pools for managing sender reputation.
• Error Handling and Logging: Implement robust error handling in your application to gracefully manage API failures or email delivery issues. Log Mandrill responses and webhook events for debugging and auditing purposes.
• Monitor Analytics: Regularly review the analytics provided in the Mandrill dashboard. This includes delivery rates, open rates, click-through rates, and bounce/complaint statistics, which are vital for optimizing your email strategy.
• Security Best Practices: Beyond securing your API keys, ensure that your application adheres to general email security best practices, such as protecting recipient lists and handling personal data according to privacy regulations like GDPR.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some typical problems and their solutions:

• Invalid API Key: Double-check that the API key used in your request exactly matches the one generated in your Mandrill dashboard. Any discrepancies, including leading/trailing spaces, will result in authentication failure.
• Domain Not Verified: Ensure your sending domain has been fully verified in the Mandrill dashboard. If DNS records haven't propagated or weren't entered correctly, Mandrill will reject attempts to send emails from that domain. Use a DNS lookup tool to confirm your TXT and CNAME records are visible.
• Incorrect from_email Address: The from_email address in your message payload must belong to a verified sending domain. If you're using a subdomain, ensure the root domain is verified.
• Missing Required Parameters: All Mandrill API calls require specific parameters, such as key, from_email, to, and subject (or template_name if using templates). Review the Mandrill /messages/send API reference for a complete list of required fields.
• Firewall or Network Issues: If your application is behind a strict firewall, ensure it can make outbound HTTPS requests to mandrillapp.com on port 443.
• Rate Limiting: While less common for a first call, be aware that Mandrill enforces rate limits. If you're rapidly testing, you might hit these limits. The API response will typically indicate a rate limit error.
• Mandrill Account Status: Confirm your Mandrill add-on is active and your Mailchimp account is in good standing. If your Mailchimp subscription lapses, Mandrill services may be suspended.

Always inspect the API response for detailed error messages. Mandrill's API typically returns descriptive JSON error objects that can guide your troubleshooting efforts.