MailChimp STS API v1.0 Documentation

API Endpoints

Important: Our API endpoints (or submit URLs) are datacenter specific. If a datacenter prefix is not used, then "us1" is generally assumed. Some API Wrappers have been updated to auto-switch based on API Keys. If you are not using a wrapper, you will need to hard code the endpoint into your app.

The generic format for the API endpoint is:

http://<dc>.sts.mailchimp.com/1.0/

Where <dc> should be replaced with the portion after the dash in your API Key. e.g. "us1", "us2", "uk1", etc. A solid example - say your API Key is myapikey-us2. You are in us2, so your API Endpoint would be:

http://us2.sts.mailchimp.com/1.0/

Any other URL will cause an error to be returned!

RESTful

The STS API is a mostly RESTful API. Known caveats:

  • We do not enforce usage of proper HTTP Verbs (GET/POST/etc)
  • You can consider any non-200 HTTP response code an error - the returned data will contain more detailed information
  • All methods are accessed via : http://<dc>.sts.mailchimp.com/1.0/SOME-METHOD.OUTPUT_FORMAT/

Input Parameters

All input parameters should be passed as normal HTTP request parameters, just like submitting an HTML FORM. They may be sent via either a GET or POST request, though we generally suggest using POST requests

Output Formats

We support 4 output formats. To use any of them, simply replace OUTPUT_FORMAT above with one of:

  • json (default)
  • php
  • xml
  • yaml

The response data for each of them will then be encoded in the specified format.

HTTPS / Secure Connections

HTTPS is 100% supported with valid, signed certificates for all API methods. Those manually coding Submit URLs can simply change the http to https in the URL (make sure your connection library supports HTTPS!). Some API Wrappers have switches to turn HTTPS on - others may require hacking at their source or contacting the author to include support.

Questions? Problems?

Have you run into difficulties or a method just doesn't seem to work right? Check out our API Support options here and we'll be happy to assist you.

Method & Error code docs


 
Method Categories
Email Verification
MC Stats
Sending
Stats

Email Verification Methods  

DeleteVerifiedEmailAddress(string apikey, string email)

Deletes a verified email address.

ListVerifiedEmailAddresses(string apikey)

Returns a list containing all of the email addresses that have been verified.

VerifyEmailAddress(string apikey, string email)

Verifies an email address.

MC Stats Methods  

GetBounces(string apikey, string since)

Returns all full bounce messages from the past 48 hours.

GetSendStats(string apikey, int tag_id, string since)

Returns all stats in one hour intervals.

GetTags(string apikey)

Returns all tags defined for your account along with all-time, non-unique aggregate stats for each.

GetUrlStats(string apikey, int url_id, string since)

Returns all stats in one hour intervals.

GetUrls(string apikey)

Returns all tracked urls defined for your account along with all-time, non-unique aggregate stats for each MailChimp specific - there is no Amazon alternative to this method.

Sending Methods  

SendEmail(string apikey, array message, bool track_opens, bool track_clicks, array tags)

Composes an email message based on input data, and then immediately queues the message for sending.

Stats Methods  

GetSendQuota(string apikey)

Returns the user's current activity limits.

GetSendStatistics(string apikey)

Returns the user's sending statistics.