List Management API methods

API Endpoint

https://api.madmimi.com

Note

As with all API methods, the api_key and username paramaters are required for all methods below.

Search

/audience_members/search.xml?query={query} [GET]

Performs an audience search and returns up to the first 100 results. All search methods available through the interface are available through this API. Note: if you want to return all users, regardless of suppression status, add the raw=true parameter on the end of your query.

Add New Audience List

 /audience_lists/?name={new_list_name} [POST]

Adds a new audience list

Rename Audience List

/audience_lists/{list_name}/rename?name={new_list_name} [POST]

Renames an audience list

Remove all Audience List Memberships

/audience_lists/{list_name}/clear [PUT]

Removes all memberships from an audience list.

Delete An Audience List

/audience_lists/{list_to_be_deleted} [DELETE]

Deletes an audience list - be sure to do any required URI encoding before deleting.

Get all Audience Lists

/audience_lists/lists.xml [GET]

Returns an XML response containing all of your lists.

Audience List Membership Status

/audience_members/{email_or_id}/lists.{format} [GET]

Returns all of the lists that {email_or_id} is subscribed to.

Audience Import

/audience_members?csv_file={file} [POST]

Import audience members using CSV formatted data. Returns an audience import id when successful.

Audience Import Status

/audience_imports/{audience_import_id}/status [GET]

Returns the status of an audience import.

Audience Create

/audience_members?email={email_to_create} [POST]

Creates a new audience member. This method takes an optional name parameter to set the name of the audience member.

Audience Update

/audience_members/{email} [PUT]

Update an audience member's attributes and lists. Returns a JSON object describing the audience member when successful.

Add Audience List Membership

/audience_lists/{name_of_list}/add?email={email_to_add} [POST]

Adds an existing or new email address to an audience list. If the email address is new, a new audience member. Any additional parameters (such as first_name and last_name) will be added or updated on the audience member.

Remove Audience List Membership

/audience_lists/{name_of_list}/remove?email={email_to_remove} [POST]

Removes an existing email address from an audience list

Remove Audience List Membership from All Lists

 /audience_lists/remove_all?email={email_to_remove} [POST]

Removes an existing email address from all audience lists

Get Audience List Members

/audience_members.xml [GET]

Returns audience members paged in XML format. Optional parameters are:

per_page to set the number of audience members returned per page. Must be between 1 and 100
page to set the current page to fetch
order to set the ordering. Must be one of email, first_name, last_name and created_at
raw to include suppressed audience in results (default: false)
suppressed_only to return only suppressed audience in results (default: false)

Edit Audience Member Email

/audience_members/{existing_email}/update_email?new_email={new_email} [POST]

Updates an audience member's email address

Get Audience List Members

/audience_lists/{list_nameORlist_id}/members.{format} [GET]

Returns audience members of the list list_name paged in XML format. Optional parameters are:

format one of xml, json or csv
per_page to set the number of audience members returned per page. Must be between 1 and 100
page to set the current page to fetch
order to set the ordering. Must be one of email, first_name, last_name, created_at or membership_created_at
suppressed_only to return only those audience members that are explicitly suppressed from the list in results (default: false)

Is Suppressed

/audience_members/{email}/is_suppressed [GET]

Checks if audience member is suppressed. Returns true: suppressed, false: not suppressed, or {email} does not exist

Suppress email

/audience_members/{email}/suppress_email [POST]

Suppresses email (unsubscribes)

Events since

/audience_members/events_since/{time_stamp}.xml [GET]

Returns an XML file containing all audience member signup and unsubscribe events. This method supports various filters like email, action_type, list_name and only_list.

Suppressed since

/audience_members/suppressed_since/{time_stamp}.txt [GET]

Returns a simple text response containing all email addresses added to your suppression list since {time_stamp} which is a Unix time stamp.

Optionally, you could add a parameter show_suppression_reason=true to include the suppression reason in the response:

/audience_members/suppressed_since/{time_stamp}.txt?show_suppression_reason=true [GET]