Mailer API

The 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://api.madmimi.com/mailer with the following form data:

  username=YourEmailAddress
  api_key=YourApiKey
  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
  reply_to=Nicholas Young <nicholas@example.com>
  body=--- \nname: Some YAML data\n

This will grab your Mad Mimi promotion named "Welcome to Acme Widgets" (if you don't already have it, you'll need to create it) and send it to dave@example.com. While we'll at it, we will import Dave Hoover into your Mad Mimi audience. We 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. If you don't want a different reply-to address, just don't pass that parameter in. :)

But, wait... I want to use my own HTML...

Ah, yes, we've seen this before. Just modify the request parameters above:

  username=YourEmailAddress
  api_key=MadMimiApiKey
  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
  raw_html=yourhtml

Just make sure that..

▪ Your HTML doesn't define Content-Type in the head tag
▪ You include the [[tracking_beacon]] macro somewhere inside the body, so we can track your email
▪ To send to a list, replace the recipient parameter with list_name, and supply the URL encoded name of your list as the list_name value.
▪ If you're sending to a list, that you have the [[unsubscribe]] macro in as well.
▪ If you're sending out a lot of emails, try to use the same several promotion names for them. Don't use a new promotion name for each one. You can use promotion names that don't exist yet, Mimi will create them for you automatically.
▪ Don't use the name of a promotion you've created using the Mad Mimi web interface, or that promotion will be overwritten.

What about plain text?

Glad you asked... The request parameters are identical to the Raw HTML, except instead of raw_html you'll want to use raw_plain_text=yourplaintext

Mailer API methods

Send transactional email

POST to https://api.madmimi.com.com/mailer

Sends a single transactional email to the recipient. Returns a unique transaction id if successful.

Send to a List

POST to https://api.madmimi.com/mailer/to_list

Sends a promotion to a list. Returns a unique mailing id if successful.

Import and Send to a List

POST to https://api.madmimi.com/mailer/to_imported_list

Imports a list of audience members (by importing the members included in the @csv_file@ parameter value) into an audience list, then sends the promotion to that audience list. Uses the same parameters as to_list with the exception that it requires the @csv_file@ parameter. Returns a unique audience import id if successful.

Send to all

POST to https://api.madmimi.com/mailer/to_all

Sends a promotion to a list. Uses the same parameters as to_list with the exception of the audience list. Returns a unique mailing id if successful.

Transactional Mailing Status

GET https://api.madmimi.com/mailers/status/{transaction-id}

Get the status of a transaction mailing.

Articles about the Mailer API

There is a good walkthrough of the core of the Mailer API using the mad_mimi_mailer gem version 0.1.0 in the the Mail on Rails article in the October 2009 edition of the PragPub magazine.