Sign up free first »

Mad Mimi Developer Area

We want Mad Mimi's APIs to feel as clean and simple as its user interface. One of the keys to Mad Mimi's success is listening to its users and incorporating their feedback. So don't hesitate to Tweet or email your experiences, frustrations, thoughts and ideas and we'll make improvements. If you would like quick, expert help with the API, please feel free to join our new Google Group. Also, you can get a nice, free walkthrough of the core of the Mailer API in the the Mail on Rails article in the October 2009 edition of the PragPub magazine.

Mad Mimi's Mailer API

Our latest and greatest developer-friendly feature is Mad Mimi's Mailer API that lets you use Mad Mimi to send your transactional emails like welcome letters, password resets, and account activations. You can also use it to programmatically send promotional emails to an audience list. Starting at $10 a month, you can use Mad Mimi to deliver your emails. To send a transactional email, just POST to https://madmimi.com/mailer with the following form data: 

  username=YourMadMimiEmailAddress
  api_key=YourMadMimiApiKey
  promotion_name=Welcome to Acme Widgets
  recipient=Dave Hoover <dave@example.com>
  subject=Welcome to Acme Widgets
  bcc=admin@example.com
  from=no-reply@example.com
  body=--- \nname: Some YAML data\n

This will grab your Mad Mimi promotion named "Welcome to Acme Widgets" and send it to dave@example.com. While she's at it, Mimi will import Dave Hoover into your Mad Mimi audience. Mimi will also replace any instances of {name} in your promotion's content with "Some YAML data". Please make sure you have plenty of room in your plan to accommodate all of the people you'll be sending emails to.

The response from a successful Mailer API delivery will have a 200 HTTP status code. The body of the response will be a transaction ID, like: 

  279132129028

You can use this transaction ID to check on the status of your email delivery. Just GET https://madmimi.com/mailers/status/<transaction-id> and you will receive one of the following statuses: 

  ignorant
  sending
  failed
  sent
  received
  clicked_through
  bounced
  retried
  retry_failed
  abused

Remember, just like all API methods, to include your username and api_key in the request, like this: https://madmimi.com/mailers/status/<transaction-id>?username=<YourMadMimiEmailAddress>&api_key=<YouMadMimiApiKey>

To send a promotional email to an audience list, just POST to https://madmimi.com/mailer/to_list with the following form data: 

  username=YourMadMimiEmailAddress
  api_key=YourMadMimiApiKey
  promotion_name=Learn more about Acme Widgets
  list_name=New Customers
  body=--- \ntopic: Spinning your Widget\n

Note: The first time you call the Mailer API, a 403 HTTP status code will be returned and we will be notified of your attempt. The Mad Mimi support team will be reviewing your account for approval.

Ruby's mad_mimi_mailer Gem

If you're into Ruby and Rails, you'll feel at home with the mad_mimi_mailer gem, which makes using the Mailer API as easy as using ActionMailer. 

  MadMimiMailer.api_settings = {
    :username => 'dave@example.com',
    :api_key => '75aFake1eApi53eKey1ffOk7acbcc300'
  }
  
  class UserNotifier < MadMimiMailer
    def mimi_welcome(user)
      subject "Welcome to Acme Widgets"
      recipients user.email
      bcc ADMIN_PEEPS
      from "admin@example.com"
      body :username => user.name,
           :email => user.email,
           :password => user.password
    end

    def reset(user)
      subject "Resetting your Acme Widgets account"
      recipients user.email
      bcc ADMIN_PEEPS
      from "admin@example.com"
      body :user => user
    end
  end

  user = User.first

  # Sent via Mad Mimi
  UserNotifier.deliver_mimi_welcome(user)

  # Sent via good old ActionMailer
  UserNotifier.deliver_reset(user)

Nicholas Young's MadMailer class for PHP 5

We haven't left PHP users out in the cold. If this long-established language is your platform of choice, we've got you covered - all you need is PHP 5 (to ensure compatibility) and cURL, compiled with OpenSSL. Then, grab the class and send away! 

  Before we dive in, a few words of guidance...

  $recipient = Everything regarding the person we're sending email to.
  $message = Any other message settings - i.e. the promotion name, subject, etc.
  $body = The keys are your YAML elements, and the values are what will be output into the message.
  
  require('MadMailer.php');
  

  Require the class above the other PHP code.
  
  
  $recipient = array('Name' => 'Nicholas Young',
         'Email' => 'nicholas@nicholaswyoung.com');
  

  Set up your recipient.
  

  $message = array('Subject' => 'This is the subject',
       'PromoName' => 'My Awesome Promotion',
       'FromAddr' => 'noreply@mydomain.com');
  

  Configure the message settings.
  

  $body = array('FIRSTNAME' => $recipient['Name'],
          'GREETING' => 'Hello from MadMailer');
  

  Remember, specify the values for whatever placeholders that are in your promotion in the $body array.
  These values are arranged as KEY => VALUE. For instance, in this promotion, I have a key called GREETING
  that gets replaced with "Hello From MadMailer" when the promotion is sent.
  

  $mailer = new MadMailer('YOUR MADMIMI LOGIN EMAIL ADDRESS', 'YOUR API KEY', false, true);
  

  Initialize the mailer class...
  
  A note about the two last parameters: the first is a debugger, when set to true,
  you'll get a print out of the mailer request string sent back to you. The second
  allows you to print out the transaction id that MadMimi returns (if set to true).
  
  $mailer->SendMessage($recipient, $message, $body);
  
  ...and send the message!

But wait! There's more!

There is an ever-expanding free API to facilitate Mad Mimi integration. Please have a look and let us know if there are other integration points you'd like us to expose!