We're experiencing a mailing rendering issue. The issue began at 5am EST and we're currently working in it. Get status updates on Twitter

Mad Mimi API

The Mad Mimi API allows simple programmatic access via HTTP to specific features of Mad Mimi. You can use any programming language that speaks HTTP to interact with Mad Mimi's API. If you would like quick, expert help with the API, please feel free to join our new Google Group.

Currently, the Mad Mimi API provides: Audience Import, Audience List Add/Delete, Audience List Membership Status/Add/Remove, and Suppressed Since. We plan to add more features in the not-too-distant-future, so let us know what would be helpful to you. Have a look at the following examples and explanations to learn how to use them.

Audience List Add

In English

POST to http://madmimi.com/audience_lists with 3 parameters:

Your Mad Mimi username
Your Mad Mimi API Key
The name of the new Audience List

In Ruby

require 'net/http'

url = URI.parse('http://madmimi.com/audience_lists')
response = Net::HTTP.post_form(url, {
  'username' => 'your.email@example.com', 
  'api_key' => '14e50ff1e51a09b956767897750e2664', 
  'name' => 'NewList'
})

Audience List Delete

In English

POST to http://madmimi.com/audience_lists/NameOfListToBeDeleted with 3 parameters:

Your Mad Mimi username
Your Mad Mimi API Key
A parameter telling Mimi to delete the list

In Ruby

require 'net/http'

url = URI.parse('http://madmimi.com/audience_lists/NameOfListToBeDeleted')
response = Net::HTTP.post_form(url, {
  'username' => 'your.email@example.com', 
  'api_key' => '14e50ff1e51a09b956767897750e2664', 
  '_method' => 'delete'
})

Audience Lists

In English

GET http://madmimi.com/audience_lists/lists.xml with 2 parameters:

Your Mad Mimi username
Your Mad Mimi API Key

Sample output

An XML response containing all of your lists.

<lists>
	<list name="test_list" id="8"/>
	<list name="another_test" id="7"/>
	<list name="test_customizations" id="5"/>
</lists>

Audience Import

In English

POST to http://madmimi.com/audience_members with 3 parameters:

Your Mad Mimi username
Your Mad Mimi API Key
A csv_file OR unstructured input

Sample input

The CSV file should have a header row with column names like: "name", "first name", "dog", "band name", "opt out", and "email". Email is the only required column and you can use any names you'd like for the rest. Here is a sample:

first name,last name,email
dave,hoover,dave@example.com
colin,harris,colin@example.com

Here is a sample that includes list support (Dave is in two lists):

name,email,add_list
dave hoover,dave@example.com,customer
dave hoover,dave@example.com,premium
colin harris,colin@example.com,customer

Here is a sample that includes opt-out support (Dave has opted out):

email,opt-out
dave@example.com,1
colin@example.com,

The unstructured input can look like:

dave@example.com, "Colin Harris" 
joe@example.com
"Gary"

In Ruby

require 'net/http'

csv_data = "email\ndave@example.com\ncolin@example.com"

url = URI.parse('http://madmimi.com/audience_members')
response = Net::HTTP.post_form(url, {
  'username' => 'your.email@example.com', 
  'api_key' => '14e50ff1e51a09b956767897750e2664', 
  'csv_file' => csv_data
})

In Perl

use LWP::UserAgent;

my csv_data = "email\ndave\@example.com\ncolin\@example.com";

my $ua = LWP::UserAgent->new;
my $req = HTTP::Request->new(POST => 'http://madmimi.com/audience_members');
$req->content("username=your.email\@example.com&api_key=14e50ff1e51a09b956767897750e2664&csv_file=$csv_data");

# Pass request to the user agent and get a response back
my $res = $ua->request($req);

In PHP — Courtesy of Geert De Deckere

<?php

$username = 'your.email@example.com';
$api_key = '14e50ff1e51a09b956767897750e2664';
$csv_data = "email\ndave@example.com\ncolin@example.com";

$ch = curl_init('http://madmimi.com/audience_members');
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS,
'username='.$username.'&api_key='.$api_key.'&csv_file='.$csv_data);
$response = curl_exec($ch);

VB.NET ASP.NET — Courtesy of Paul Anthony

Public Sub SendtoMadMimi()

Dim objStringBuilder As New StringBuilder()
objStringBuilder.AppendLine("email")
objStringBuilder.AppendLine("dave@example.com")
objStringBuilder.AppendLine("colin@example.com")

Dim MyMadMimiUserName As String = "your.email@example.com"
Dim MyMadMimiApiKey As String = "14e50ff1e51a09b956767897750e2664" 
Dim MyMadMimiData As string = objStringBuilder.ToString()

Dim encoding As New ASCIIEncoding()
Dim postData As String
postData = "username=" _

 & MyMadMimiUserName & "_
 &api_key=" & MyMadMimiApiKey & "&csv_file="_
 & MyMadMimiData


Dim data As Byte() = encoding.GetBytes(postData)
Dim myURL As String
myURL = "http://madmimi.com/audience_members"
Dim myRequest As HttpWebRequest
myRequest = DirectCast(WebRequest.Create(myURL), HttpWebRequest)
myRequest.Method = "POST"
myRequest.ContentType = "application/x-www-form-urlencoded"
myRequest.ContentLength = data.Length
Dim newStream As Stream = myRequest.GetRequestStream()
newStream.Write(data, 0, data.Length)
newStream.Close()

End Sub

You can really use many other languages that can consume web services with the API, and if you have any samples of languages other than what we have listed here, please let us know!

Audience List Membership Status

In English

GET http://madmimi.com/audience_members/dave@example.com/lists.xml with 2 parameters:

Your Mad Mimi username
Your Mad Mimi API Key

Sample output

An XML response with the lists the person is a member of.

<lists>
	<list name="test_list" id="8"/>
	<list name="another_test" id="7"/>
	<list name="test_customizations" id="5"/>
</lists>

Add Audience List Membership

In English

POST to http://madmimi.com/audience_lists/NameOfList/add with 3 parameters:

Your Mad Mimi username
Your Mad Mimi API Key
email address of an existing audience member to add to the list

In Ruby

require 'net/http'

url = URI.parse('http://madmimi.com/audience_lists/NameOfList/add')
response = Net::HTTP.post_form(url, {
  'username' => 'your.email@example.com', 
  'api_key' => '14e50ff1e51a09b956767897750e2664', 
  'email' => 'tom@example.com'
})

Remove Audience List Membership

In English

POST to http://madmimi.com/audience_lists/NameOfList/remove with 3 parameters:

Your Mad Mimi username
Your Mad Mimi API Key
email address of an existing audience member to remove from the list

In Ruby

require 'net/http'

url = URI.parse('http://madmimi.com/audience_lists/NameOfList/remove')
response = Net::HTTP.post_form(url, {
  'username' => 'your.email@example.com', 
  'api_key' => '14e50ff1e51a09b956767897750e2664', 
  'email' => 'dave@example.com'
})

Suppressed Since

In English

GET http://madmimi.com/audience_members/suppressed_since/1267104774.txt with 2 parameters:

Your Mad Mimi username
Your Mad Mimi API Key

Sample output

A plain text, newline separated list of email addresses will be returned. These are the email addresses that have "suppressed" (a.k.a. "opted out") from your audience since 2 weeks ago (a.k.a. 1267104774 seconds since 1 January 1970). You can adjust that number to represent any arbitrary date. The output would look something like this:

dave@example.com
colin@example.com
tom@example.com

Mailing Stats

In English

GET http://madmimi.com/promotions.xml with 2 parameters:

Your Mad Mimi username
Your Mad Mimi API Key

Sample output

The response is an xml file of all your promotions with ids. Each entry has the promotion's mailings with an id.

<promotions>
	<promotion name="Test" id="90389" updated_at="Wed Oct 28 12:21:04 -0400 2009">
		<mailing id="202773">
			<started_send>Tue Oct 27 16:39:29 -0400 2009</started_send>
			<finished_send>Tue Oct 27 16:39:40 -0400 2009</finished_send>
		</mailing>
		...
	</promotion?
	...
</promotions>

Now GET http://madmimi.com/promotions/<promotion_id>/mailings/<mailing_id>.xml with 2 parameters:

Your Mad Mimi username
Your Mad Mimi API Key

Sample output

An XML response with statistics for that mailing.

<mailing>
	<sent>2</sent>
	<views>2</views>
	<untraced>0</untraced>
	<clicked>0</clicked>
	<links> </links>
	<forwarded>0</forwarded>
	<bounced>0</bounced>
	<unsubscribed>2</unsubscribed>
</mailing>