Mailchimp Transactional

Common errors

Warnings

Install compatibility verified last tested: 2026-05-12

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 verified last tested: 2026-04-23

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)