Mailchimp Transactional

Common errors

• ModuleNotFoundError: No module named 'mailchimp-transactional'

  cause The package was installed using 'mailchimp-transactional' (hyphen) but is imported using 'mailchimp_transactional' (underscore).
  fix Change the import statement to `import mailchimp_transactional` or `from mailchimp_transactional import Client`.

• AttributeError: 'MailchimpTransactionalClient' object has no attribute 'messages'

  cause You are attempting to call an email-related method (like `send`) directly on the client object, rather than through its `messages` sub-client.
  fix Access the `messages` sub-client first: `client.messages.send(message=...)`.

• MailchimpTransactionalError: Invalid API Key

  cause The provided API key is incorrect, expired, or the Mailchimp account associated with the key does not have an active Standard plan or higher, which is required for Mailchimp Transactional Email.
  fix Verify your Mailchimp Transactional API key in your Mailchimp account and ensure your account is on a Standard plan or higher.

• TypeError: send() missing 1 required positional argument: 'message'

  cause The `client.messages.send()` method requires a dictionary named `message` containing all the email's details (e.g., recipients, subject, body).
  fix Provide a dictionary as the `message` argument: `client.messages.send(message={'to': [{'email': 'recipient@example.com'}], 'from_email': 'sender@example.com', 'subject': 'Test Subject', 'html': '<p>Test content</p>'})`.

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
  wrong:

  import mailchimp-transactional  # SyntaxError — use underscore
  import mailchimp               # wrong package entirely

  correct:

  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
  wrong:

  # Wrong: using Mailchimp Marketing API key instead of Mandrill/Transactional key
  client = MailchimpTransactional.Client('YOUR_MAILCHIMP_MARKETING_API_KEY')
  # Returns 401 Invalid API Key — these are separate keys

  correct:

  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)