API reference

Email content

Create and edit the email content that EmailMarketer.io campaigns, journeys and confirmations send, preview it, and run spam checks through the API.

An email holds the subject, sender, HTML and text that a campaign, journey step or opt-in confirmation sends. All commands take APIKey and are sent to POST https://app.emailmarketer.io/api.php with Command, or to the /api/v1/ path shown.

email.create

Creates an empty email and returns its ID. Fill it with email.update.

curl https://app.emailmarketer.io/api.php \
  -d Command=email.create \
  -d APIKey="$EM_API_KEY"
{ "Success": true, "ErrorCode": 0, "EmailID": 12345 }

email.update

Parameter Required Description
EmailID Yes
ValidateScope Yes Campaign, AutoResponder or OptIn. Sets which checks run, such as the unsubscribe link
EmailName No Internal name
Subject, PreHeaderText No
FromName, FromEmail, ReplyToName, ReplyToEmail No FromEmail must be on a verified sender domain
HTMLContent, PlainContent No Body
Mode No How the content was made, for example Editor, Template, Import or Empty
RelTemplateID When Mode is Template
FetchURL, FetchPlainURL No Load the content from a URL
ImageEmbedding No Embed images in the message
SenderDomain No The sender domain to send through
OpenTracking, LinkTracking No Turn tracking on or off for this email
UTMTracking No Add UTM tags to links. Needs UTMSource, UTMMedium and UTMCampaign. Optional UTMTerm, UTMContent
curl https://app.emailmarketer.io/api.php \
  -d Command=email.update \
  -d APIKey="$EM_API_KEY" \
  -d EmailID=12345 \
  -d ValidateScope=Campaign \
  -d Subject="November product update"
Code Meaning
1 Missing EmailID
3 Email not found
4 Invalid Mode
8 Empty content
9, 10 Missing or invalid ValidateScope
11, 12 The unsubscribe link %Link:Unsubscribe% is missing from the HTML or the text content
17 Invalid sender domain
18 to 20 A required UTM value is missing
21 FromEmail has no domain
22 A campaign that uses this email is sending
23 FromEmail is not allowed

Merge tags

Insert subscriber data with %Subscriber:<field>%, for example %Subscriber:EmailAddress% or %Subscriber:CustomField12% for custom field 12. Campaign emails must contain the unsubscribe link %Link:Unsubscribe%. email.personalizationtags lists every tag you can use.

Read, copy and delete

Command Required Optional Returns Errors
email.get EmailID none EmailInformation (EmailName, Subject, HTMLContent, PlainContent, FromName, FromEmail) 1 missing, 2 not found
emails.get none EmailIDs (up to 100), Fields (columns to return) TotalEmailCount, Emails 1 no valid IDs, 3 more than 100
email.duplicate EmailID none New EmailID and EmailName 1 missing, 2 not found
email.delete EmailID none Success 1 missing
attachment.delete AttachmentID none Success 1 missing

Examples:

# email.get
curl https://app.emailmarketer.io/api.php \
  -d Command=email.get \
  -d APIKey="$EM_API_KEY" \
  -d EmailID=12345

# emails.get
curl https://app.emailmarketer.io/api.php \
  -d Command=emails.get \
  -d APIKey="$EM_API_KEY" \
  -d EmailIDs=12345,12346

# email.duplicate
curl https://app.emailmarketer.io/api.php \
  -d Command=email.duplicate \
  -d APIKey="$EM_API_KEY" \
  -d EmailID=12345

# email.delete
curl https://app.emailmarketer.io/api.php \
  -d Command=email.delete \
  -d APIKey="$EM_API_KEY" \
  -d EmailID=12345

# attachment.delete
curl https://app.emailmarketer.io/api.php \
  -d Command=attachment.delete \
  -d APIKey="$EM_API_KEY" \
  -d AttachmentID=55

Test and preview

email.emailpreview

Sends a test of an email to one address.

Parameter Description
EmailID The email, or send HTMLContent and PlainTextContent instead
EmailAddress Where to send the test, unless SubscriberID is given
SubscriberID, ListID, CampaignID Personalise the test as that subscriber
FromName, FromEmailAddress, Subject, PreHeaderText, ReplyToName, ReplyToEmail, SenderDomain Override for this test
curl https://app.emailmarketer.io/api.php \
  -d Command=email.emailpreview \
  -d APIKey="$EM_API_KEY" \
  -d EmailID=12345 \
  -d EmailAddress=jane@example.com

Errors: 1 missing EmailID, 2 missing address, 3 email not found, 4 invalid address, 5 subscriber, 6 list or 7 campaign not found, 8 delivery failed, 9 and 10 content missing, 20 too many tests (with RetryAfter), 21 the recipient is suppressed.

email.spamtest

Runs a spam score check. Requires EmailID.

curl https://app.emailmarketer.io/api.php \
  -d Command=email.spamtest \
  -d APIKey="$EM_API_KEY" \
  -d EmailID=12345
{ "Success": true, "ErrorCode": 0, "TestResults": { "score": 1.2, "tests": [{ "name": "HTML_IMAGE_RATIO_02", "score": 0.4, "description": "..." }] } }

Errors: 1 missing, 2 not found, 3 the check service failed.

Render

Command Path Returns
email.render GET /api/v1/email.render Subject and EmailContent as a subscriber would get them. Needs ListID, SubscriberID, CampaignID, EmailID and related IDs
email.personalizationtags POST /api.php Merge tags you can use. Scope (array: Subscriber, CampaignLinks, OptLinks, ListLinks, AllLinks, User), plus ListID when the scope includes Subscriber
email.html2text POST /api/v1/email.html2text PlainContent made from HTMLContent

Examples:

# email.render
curl -G https://app.emailmarketer.io/api/v1/email.render \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d SubscriberID=456 \
  -d CampaignID=12345 \
  -d EmailID=678

# email.personalizationtags
curl https://app.emailmarketer.io/api.php \
  -H "Content-Type: application/json" \
  -d '{ "Command": "email.personalizationtags", "APIKey": "'"$EM_API_KEY"'", "Scope": ["Subscriber", "AllLinks"], "ListID": 123 }'

# email.html2text
curl https://app.emailmarketer.io/api/v1/email.html2text \
  -d APIKey="$EM_API_KEY" \
  --data-urlencode HTMLContent='<p>Thanks for your order.</p>'

One header and footer per account, added to emails.

Command Path Parameters
user.emailcontent.get GET /api/v1/user.emailcontent none. Returns PlainEmailHeader, PlainEmailFooter, HTMLEmailHeader, HTMLEmailFooter
user.emailcontent.update PATCH /api/v1/user.emailcontent Any of the four fields. Omitted fields are kept. "" clears one. JSON body only

Examples:

# user.emailcontent.get
curl -G https://app.emailmarketer.io/api/v1/user.emailcontent \
  -d APIKey="$EM_API_KEY"

# user.emailcontent.update
curl -X PATCH https://app.emailmarketer.io/api/v1/user.emailcontent \
  -H "Content-Type: application/json" \
  -d '{ "APIKey": "'"$EM_API_KEY"'", "HTMLEmailFooter": "<p>Acme, 1 Main Street</p>" }'