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