Mailchimp Transactional

Warnings

• breaking Install name and import name differ. pip install mailchimp-transactional (hyphen), then import mailchimp_transactional (underscore). LLMs frequently generate import mailchimp-transactional which is a SyntaxError.
  Fix: pip install mailchimp-transactional then import mailchimp_transactional as MailchimpTransactional
• breaking Requires paid Mailchimp Standard plan or higher. The Transactional API (formerly Mandrill) is NOT available on free Mailchimp accounts. Attempting to use a free account API key returns: 'This account does not have access to the Transactional API.'
  Fix: Upgrade to Mailchimp Standard or Premium plan to enable Transactional. Enable it in Mailchimp account Billing settings.
• breaking Mandrill/Transactional API key is SEPARATE from the Mailchimp Marketing API key. Using the wrong key returns 401 Invalid API Key errors. Transactional keys are generated at mandrillapp.com settings.
  Fix: Get your Mandrill API key from: mandrillapp.com → Settings → SMTP & API Info → Add API Key. This is a different key from mailchimp.com API keys.
• gotcha All API requests are HTTP POST, not RESTful GET/PUT/DELETE. The entire API surface (including read operations like messages.search) uses POST. The Python client handles this transparently but raw HTTP implementations must use POST.
  Fix: All endpoint calls via the Python client use POST automatically. If calling the API directly: all requests go to https://mandrillapp.com/api/1.0/ENDPOINT.json via POST with JSON body.
• gotcha The API base URL is still mandrillapp.com (not mailchimp.com), a legacy artifact of the Mandrill → Mailchimp Transactional rebrand. Documentation still references both names interchangeably.
  Fix: Use the Python client which handles the base URL. If calling raw: https://mandrillapp.com/api/1.0/ is the correct base.
• gotcha Sending from an unverified domain silently soft-fails or degrades deliverability. DKIM and DMARC must be configured for the sending domain before production use.
  Fix: Verify your sending domain at mandrillapp.com → Sending Domains. Set up DKIM (TXT record mandrill._domainkey.yourdomain.com) and a DMARC policy (p=none minimum).

Install

• pip install mailchimp-transactional Standard (hyphen in install name)

Imports

• mailchimp_transactional

  import mailchimp_transactional as MailchimpTransactional
  from mailchimp_transactional.api_client import ApiClientError
  
  try:
      client = MailchimpTransactional.Client('YOUR_MANDRILL_API_KEY')
      response = client.users.ping()
      print('API called successfully: {}'.format(response))
  except ApiClientError as error:
      print('An exception occurred: {}'.format(error.text))

  Install with pip install mailchimp-transactional (hyphen). Import as import mailchimp_transactional (underscore). These are different strings — a consistent LLM confusion source.
• messages.send

  response = client.messages.send({
      'message': {
          'from_email': 'hello@yourdomain.com',
          'subject': 'Hello',
          'text': 'Welcome!',
          'to': [{
              'email': 'recipient@example.com',
              'type': 'to'
          }]
      }
  })

  The Transactional API uses a Mandrill API key, NOT the Mailchimp Marketing API key. They are separate credentials generated at mandrillapp.com settings, not mailchimp.com.

Quickstart

Basic send pattern. Always catch ApiClientError. Verify with users.ping() first.

import mailchimp_transactional as MailchimpTransactional
from mailchimp_transactional.api_client import ApiClientError

client = MailchimpTransactional.Client('YOUR_MANDRILL_API_KEY')

# Verify API key works
try:
    response = client.users.ping()
    print('Ping:', response)  # 'PONG!'
except ApiClientError as e:
    print('Error:', e.text)

# Send a transactional email
try:
    response = client.messages.send({
        'message': {
            'from_email': 'noreply@yourdomain.com',
            'from_name': 'Your App',
            'subject': 'Password Reset',
            'html': '<p>Click <a href="{reset_url}">here</a> to reset your password.</p>',
            'to': [{'email': 'user@example.com', 'type': 'to'}],
            'track_opens': True,
            'track_clicks': True
        }
    })
    print('Sent:', response)
except ApiClientError as e:
    print('Send failed:', e.text)