API reference

Lists

Create, read, update, copy, archive and delete EmailMarketer.io subscriber lists, and read list reports through the API.

A list holds subscribers, custom fields, segments and tags. All commands take APIKey. Send them to https://app.emailmarketer.io/api.php with Command, or to the /api/v1/ path shown.

list.create

POST /api.php.

Parameter Type Required Description
SubscriberListName string Yes List name
Description string No
OptInMode string No Single (default) or Double
SenderName, SenderEmailAddress, SenderCompany, SenderAddress string No Default sender and postal address for the list
ConfirmationEmail object No Creates the double opt-in email with the list. Needs Subject, FromName, FromEmail, ContentType (HTML, Plain or Both) and the matching HTMLContent or PlainContent. Optional ReplyToName, ReplyToEmail, PreHeaderText, EmailName

Sending ConfirmationEmail switches the list to double opt-in. If the email cannot be created, the list is not created either.

curl https://app.emailmarketer.io/api.php \
  -d Command=list.create \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberListName=Newsletter \
  -d Description="Monthly product news"
{ "Success": true, "ErrorCode": 0, "ListID": 123, "ConfirmationEmailID": 567 }
Code Meaning
1 Missing name
3 List limit reached
20 Invalid OptInMode
21 A ConfirmationEmail field is missing
22 Invalid ContentType
23, 24 HTMLContent or PlainContent is required
27, 28 The confirmation or sender address is not allowed
30 The confirmation email could not be created. Nothing was saved

list.get

POST /api.php. Requires ListID. Optional GetStats adds statistics.

curl https://app.emailmarketer.io/api.php \
  -d Command=list.get \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d GetStats=true
{ "Success": true, "ErrorCode": 0, "List": { "ListID": 123, "Name": "Newsletter", "OptInMode": "Double", "Options": {} } }

Error 1: missing ListID.

lists.get

All lists. GET /api/v1/lists.get.

Parameter Type Description
RecordsPerRequest int 0 returns all
RecordsFrom int Offset
OrderField string ListID, Name, CreatedOn, ArchivedAt, ActiveSubscriberCount, SegmentCount or LastActivityAt
OrderType string ASC or DESC
Search string Matches name and description
Archived string false (default), true or all
curl https://app.emailmarketer.io/api.php \
  -d Command=lists.get \
  -d APIKey="$EM_API_KEY" \
  -d Search=Newsletter
{ "Success": true, "ErrorCode": 0, "TotalListCount": 5, "Lists": [{ "ListID": 123, "Name": "Newsletter", "OptInMode": "Single", "SubscriberCount": 12345, "ActiveSubscriberCount": 12001, "SegmentCount": 4, "ArchivedAt": null }] }

lists.overview

All lists with their custom fields, segments and tags in one call. POST /api.php.

Parameter Type Description
IncludeCustomFields, IncludeSegments, IncludeSubscriberTags bool Default false
Archived string active (default), archived or all
Search string
OrderField string ListID, Name (default) or CreatedOn
OrderType string ASC or DESC

Account-wide custom fields are included in every list’s CustomFields.

curl https://app.emailmarketer.io/api.php \
  -d Command=lists.overview \
  -d APIKey="$EM_API_KEY" \
  -d IncludeCustomFields=true

list.update

POST /api.php. Requires SubscriberListID. Send only what you change.

Parameter Description
Name, Description An empty Description clears it
SenderName, SenderEmailAddress, SenderCompany, SenderAddress
OptInMode Single or Double
OptInConfirmationEmailID The confirmation email
OptOutAddToSuppressionList, OptOutAddToGlobalSuppressionList Yes or No. What happens to an address when it unsubscribes
OptOutScope This list or All lists
OptInSubscribeTo, OptInUnsubscribeFrom, OptOutSubscribeTo, OptOutUnsubscribeFrom List IDs to move contacts to or from on subscribe and unsubscribe. 0 clears
SubscriptionConfirmationPendingPageURL, SubscriptionConfirmedPageURL, SubscriptionErrorPageURL, UnsubscriptionConfirmedPageURL, UnsubscriptionErrorPageURL Your own pages to redirect to
Options Object, merged with the stored options. Keys include HTMLEmailHeader, HTMLEmailFooter, PlainEmailHeader, PlainEmailFooter and DoNotSendEmailCampaignIfRecipientIsEnrolledInJourneyOrAutoresponder
curl https://app.emailmarketer.io/api.php \
  -d Command=list.update \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberListID=123 \
  -d Name="Monthly newsletter"

Returns the updated List.

Code Meaning
1, 2 Missing or invalid list ID
3 Invalid opt-in mode
4 Invalid opt-out scope
10 Invalid suppression option
11 Nothing to update
23 Invalid list ID in a subscribe or unsubscribe setting
24 Invalid email ID
25 The sender address is not allowed

Copy, archive and delete

Command Path Required Optional Returns Errors
list.clone POST /api/v1/list.clone SubscriberListID, Name IncludeCustomFields (default true) ListID, CustomFieldsCloned 1 missing source, 2 missing name or invalid source, 3 list limit reached, 4 copy failed
list.archive POST /api.php SubscriberListID none Success 1 missing ID, 2 not found
list.unarchive POST /api.php SubscriberListID none Success 1 missing ID, 2 not found
lists.delete POST /api.php Lists (comma-separated IDs) none Success 1 missing IDs
list.assets POST /api.php ListID none The list with its segments, custom fields, tags and autoresponders 1 missing ID

Examples:

# list.clone
curl https://app.emailmarketer.io/api/v1/list.clone \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberListID=123 \
  -d Name="Newsletter copy"

# list.archive
curl https://app.emailmarketer.io/api.php \
  -d Command=list.archive \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberListID=123

# list.unarchive
curl https://app.emailmarketer.io/api.php \
  -d Command=list.unarchive \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberListID=123

# lists.delete
curl https://app.emailmarketer.io/api.php \
  -d Command=lists.delete \
  -d APIKey="$EM_API_KEY" \
  -d Lists=123,124

# list.assets
curl https://app.emailmarketer.io/api.php \
  -d Command=list.assets \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123

list.clone copies settings and fields, not subscribers. Deleting a list deletes its subscribers.

Sign-up form code

listintegration.generatesubscriptionformhtmlcode returns HTML for a sign-up form. Requires SubscriberListID. Optional CustomFields (comma-separated field IDs), EmailAddressString (label), SubscribeButtonString. listintegration.generateunsubscriptionformhtmlcode does the same for an unsubscribe form.

Examples:

# listintegration.generatesubscriptionformhtmlcode
curl https://app.emailmarketer.io/api.php \
  -d Command=listintegration.generatesubscriptionformhtmlcode \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberListID=123 \
  -d CustomFields=12,13

# listintegration.generateunsubscriptionformhtmlcode
curl https://app.emailmarketer.io/api.php \
  -d Command=listintegration.generateunsubscriptionformhtmlcode \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberListID=123

Reports

All take ListID unless noted and return the list ID with the data. Errors: 99997 when the list does not exist or is not yours.

Command Optional Returns
lists.stats (GET /api/v1/lists.stats, no ListID) Days (1 to 365, default 30), ListIDs Per list: active subscribers, unique opens and clicks, sent, net growth, open, click and click-to-open rates as fractions
list.getactivityseries (GET /api/v1/list.getactivityseries) Days (1 to 365, default 30) Daily subscriptions, unsubscriptions, imports, bounces and net growth
list.getsubscriberstatusbreakdown none Counts by status: active, opt-in pending, soft and hard bounced, unsubscribed, complained, suppressed
list.getbouncetrend Weeks (1 to 26, default 6) Weekly sent, bounces and complaints, with percentages
list.getengagementtiers ChampionDays, EngagedDays, PassiveEndDays, LapsedEndDays, NeverEngagedJoinedDays Counts per tier: champions, engaged, passive, lapsed, dormant, never engaged
list.getsendtimeheatmap Days (default 90), Event (open or click), TimeZone (server or account) A 7 by 24 grid, Monday first
list.gettenuredistribution none Counts by how long contacts have been on the list
list.getespbreakdown Event (required: subscribers, opens, clicks or unsubscriptions), Top (default 30) Counts by mailbox domain
list.getctrretentionmatrix LastNCampaigns (default 10), CohortDepth (default 7) How many clickers of each campaign clicked again
list.getsourcebreakdown none Counts by source (CSVImport, API, Webhook, Manual, Other, Unknown) and by month

Examples:

# lists.stats
curl -G https://app.emailmarketer.io/api/v1/lists.stats \
  -d APIKey="$EM_API_KEY" \
  -d Days=30

# list.getactivityseries
curl -G https://app.emailmarketer.io/api/v1/list.getactivityseries \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d Days=30

# list.getsubscriberstatusbreakdown
curl https://app.emailmarketer.io/api.php \
  -d Command=list.getsubscriberstatusbreakdown \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123

# list.getbouncetrend
curl https://app.emailmarketer.io/api.php \
  -d Command=list.getbouncetrend \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d Weeks=12

# list.getengagementtiers
curl https://app.emailmarketer.io/api.php \
  -d Command=list.getengagementtiers \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123

# list.getsendtimeheatmap
curl https://app.emailmarketer.io/api.php \
  -d Command=list.getsendtimeheatmap \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d Event=open

# list.gettenuredistribution
curl https://app.emailmarketer.io/api.php \
  -d Command=list.gettenuredistribution \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123

# list.getespbreakdown
curl https://app.emailmarketer.io/api.php \
  -d Command=list.getespbreakdown \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d Event=opens

# list.getctrretentionmatrix
curl https://app.emailmarketer.io/api.php \
  -d Command=list.getctrretentionmatrix \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d LastNCampaigns=10

# list.getsourcebreakdown
curl https://app.emailmarketer.io/api.php \
  -d Command=list.getsourcebreakdown \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123