API reference

Subscribers

Add, find, update, unsubscribe, delete, import and export contacts on EmailMarketer.io lists through the API.

A subscriber is one contact on one list. The same email address on two lists is two subscribers with two IDs.

All commands on this page take your account API key as APIKey. Send them to https://app.emailmarketer.io/api.php with Command, or to the /api/v1/ path shown. Legacy commands return Success and ErrorCode. Commands marked Errors array return {"Errors":[{"Code","Message"}]}.

Subscription statuses are Subscribed, Opt-In Pending, Unsubscribed and Opt-Out Pending.

subscriber.create

Adds a contact to a list. POST /api/v1/subscriber.create. Errors array.

Parameter Type Required Description
ListID int Yes The list
EmailAddress string Yes The contact’s address
Status string No Subscribed (default), Opt-In Pending, Unsubscribed or Opt-Out Pending
SubscriptionDate, SubscriptionIP string When status is Subscribed or Opt-In Pending When and from where the contact subscribed
UnsubscriptionDate, UnsubscriptionIP string When status is Unsubscribed or Opt-Out Pending When and from where the contact unsubscribed
OptInDate date No Date the contact confirmed
BounceType string No Not Bounced (default), Soft or Hard
CustomFields object No { "<CustomFieldID>": "value" }
EnforceRequiredFields bool No Apply the list’s required, unique and validation rules
UpdateIfDuplicate bool No Update the contact if the address is already on the list
UpdateIfUnsubscribed bool No Re-subscribe an address that unsubscribed
SendConfirmationEmail bool No Send the list’s opt-in confirmation email
OptInConfirmationEmailID int No A different confirmation email
TriggerAutoResponders bool No Start the list’s autoresponders for this contact
TriggerWebServices bool No Run the list’s subscribe integrations
ApplyBehaviors bool No Apply the list’s subscribe behaviours
UpdateStatistics bool No Count the add in list statistics
Source string No API (default), CSVImport, Webhook, Manual, Other or Unknown
SourceRef string No Your own label for the source, up to 64 characters

All boolean options default to false.

curl https://app.emailmarketer.io/api.php \
  -d Command=subscriber.create \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d EmailAddress=jane@example.com \
  -d SubscriptionDate="2026-11-17 09:30:00" \
  -d SubscriptionIP=203.0.113.10 \
  -d UpdateIfDuplicate=true
{
  "Success": true, "ErrorCode": 0,
  "SubscriberInformation": { "SubscriberID": 456, "EmailAddress": "jane@example.com", "SubscriptionStatus": "Subscribed" },
  "Suppressed": false, "SubscriberTags": [], "SubscriberSegments": [], "SubscriberJourneys": []
}
Code Meaning
1 Missing ListID
2 Missing EmailAddress
3, 19 Invalid email address
4 Invalid ListID
5 Invalid BounceType
6 Invalid Status
7 to 16 A subscription or unsubscription date or IP is missing or invalid
17 Invalid custom field value
18 Contact limit reached
20 The address is already on the list
21 The address unsubscribed before
22, 23 Invalid account or list
24, 25 Invalid OptInConfirmationEmailID
26 A required custom field is empty (with EnforceRequiredFields)
27 A unique field value already exists (with EnforceRequiredFields)
28 A value failed field validation (with EnforceRequiredFields)

subscriber.subscribe

Public sign-up, for your own forms. It needs no API key, follows the list’s opt-in setting and returns the list’s redirect URL. POST /api.php.

Parameter Type Required Description
ListID string Yes One list ID, or up to 10 comma-separated IDs from one account
EmailAddress string Yes
IPAddress string Yes The visitor’s IP address
CustomField<ID> string No One parameter per custom field, for example CustomField12
EnforceRequiredFields bool No Apply required, unique and validation rules
UpdateIfUnsubscribed bool No Re-subscribe an address that unsubscribed. Default false
Source, SourceRef string No As in subscriber.create
curl https://app.emailmarketer.io/api.php \
  -d Command=subscriber.subscribe \
  -d ListID=123 \
  -d EmailAddress=jane@example.com \
  -d IPAddress=203.0.113.10 \
  -d CustomField12=Acme
{ "Success": true, "ErrorCode": 0, "SubscriberID": 456, "RedirectURL": "https://...", "Subscriber": { "SubscriberID": 456, "SubscriptionStatus": "Opt-In Pending" } }
Code Meaning
1, 2, 3 Missing ListID, EmailAddress or IPAddress
4 Invalid ListID
5 Invalid email address
6 A required custom field is missing. The response adds ErrorCustomFieldID and ErrorCustomFieldTitle
7 A unique value is taken by another subscriber
8 Invalid custom field value
9 Already on the list. Nothing changed
10 Subscription failed
12 The address unsubscribed and UpdateIfUnsubscribed is not true
13 The lists belong to different accounts
14 More than 10 lists
101 The address was refused

subscriber.get

Returns one subscriber with fields, tags, segments, journeys and activity. POST /api.php.

Parameter Type Required Description
ListID int Yes
EmailAddress or SubscriberID string or int Yes Who to fetch
IncludeJourneys, IncludeEvents, IncludeActivity, IncludeRevenue, IncludeTags, IncludeSegments bool No All default true. Set to false for a smaller response
curl https://app.emailmarketer.io/api.php \
  -d Command=subscriber.get \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d EmailAddress=jane@example.com \
  -d IncludeActivity=false
{
  "Success": true, "ErrorCode": 0,
  "SubscriberInformation": { "SubscriberID": 456, "EmailAddress": "jane@example.com" },
  "Suppressed": false,
  "SubscriberTags": [{ "TagID": 1, "TagName": "VIP" }],
  "SubscriberSegments": [],
  "SubscriberJourneys": { "InProgress": [], "Completed": [] },
  "SubscriberWebsiteEvents": [], "SubscriberActivity": [], "TotalRevenue": 0
}

Errors: 1 missing address or ID, 2 missing ListID, 3 not found, 4 invalid ListID, 429 too many requests.

subscriber.exists

Checks whether an address is on a list. POST /api.php. Requires ListID and EmailAddress.

curl https://app.emailmarketer.io/api.php \
  -d Command=subscriber.exists \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d EmailAddress=jane@example.com
{ "Success": true, "ErrorCode": 0, "Exists": true, "SubscriberID": 456 }

Errors: 1 missing ListID, 2 missing EmailAddress, 3 invalid ListID.

subscriber.update

Changes a subscriber’s address, status or fields. POST /api.php.

Parameter Type Required Description
SubscriberID int Yes
SubscriberListID int Yes
EmailAddress string No New address
SubscriptionStatus string No New status
UnsubscriptionIP, UnsubscriptionDate string No For a change to unsubscribed
BounceType string No Not Bounced, Soft or Hard
Fields object No { "CustomField12": "value" }. Keys are not case-sensitive
EnforceRequiredFields bool No Apply field rules
IgnoreAllOtherCustomFieldsExceptGivenOnes bool No Leave fields you did not send unchanged
TriggerEvents bool No Run triggers such as journeys. Default true
curl https://app.emailmarketer.io/api.php \
  -d Command=subscriber.update \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberID=456 \
  -d SubscriberListID=123 \
  -d EmailAddress=jane.doe@example.com

Returns {"Success":true,"ErrorCode":0}. When a status or bounce change clears a suppression, the response adds StillSuppressed if the address is still blocked elsewhere.

Errors: 1 missing SubscriberID, 2 missing SubscriberListID, 3 missing address, 4 invalid address, 5 invalid list, 6 not found, 7 duplicate address, 8 required field missing, 9 value not unique, 10 invalid value, 11 unknown custom field IDs (listed in ErrorCustomFieldIDs).

subscriber.unsubscribe

Unsubscribes one contact, or every contact that matches rules. POST /api.php.

Parameter Type Required Description
ListID int Yes
IPAddress string Yes
EmailAddress, SubscriberID or RulesJSON Yes, one of them Who to unsubscribe. RulesJSON needs RulesOperator (and or or). See Segments
CampaignID, EmailID, AutoResponderID int No Attribute the unsubscribe to a send
AddToGlobalSuppression bool No Also add the address to the account-wide suppression list
Preview int No 1 runs a dry run
curl https://app.emailmarketer.io/api.php \
  -d Command=subscriber.unsubscribe \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d IPAddress=203.0.113.10 \
  -d EmailAddress=jane@example.com \
  -d AddToGlobalSuppression=true

Returns {"Success":true,"ErrorCode":0,"RedirectURL":"..."}.

Errors: 1 missing ListID, 2 missing IPAddress, 3 missing address or ID, 4 invalid list, 6 invalid address, 7 not found or invalid RulesJSON, 8 invalid CampaignID, 9 already unsubscribed, 10 invalid EmailID, 11 query failed.

subscribers.delete

Deletes subscribers by ID or by rules. POST /api.php.

Parameter Type Required Description
SubscriberListID int Yes
Subscribers or RulesJSON string Yes, one of them Comma-separated IDs, or rules with RulesOperator
Suppressed bool No Delete from the list’s suppression entries instead
curl https://app.emailmarketer.io/api.php \
  -d Command=subscribers.delete \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberListID=123 \
  -d Subscribers=456,457

Errors: 2 missing list, 5 invalid list, 6 query failed, 7 invalid RulesJSON, 8 an ID is not an integer.

subscribers.delete.all

Deletes every subscriber on a list. POST /api.php. Requires ListID. Optional DeleteListTags also deletes the list’s tags.

curl https://app.emailmarketer.io/api.php \
  -d Command=subscribers.delete.all \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123

Errors: 1 missing ListID, 3 invalid list, 4 access denied, 5 to 8 delete failed.

subscribers.get

Pages through a list by status or segment. GET /api/v1/subscribers.get.

Parameter Type Required Description
SubscriberListID int Yes
SubscriberSegment string Yes Active, Suppressed, Unsubscribed, Soft bounced, Hard bounced, Opt-in pending, or a segment ID
RecordsPerRequest int No Default 25. Do not send 0
RecordsFrom int No Offset. Default 0
OrderField string No Default EmailAddress
OrderType string No ASC or DESC
SearchField string No EmailAddress, SubscriberID, SubscriptionDate, SubscriptionIP, OptInDate or a custom field ID
SearchKeyword string No Value to search for
curl -G https://app.emailmarketer.io/api/v1/subscribers.get \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberListID=123 \
  -d SubscriberSegment=Active \
  -d RecordsPerRequest=100
{ "Success": true, "ErrorCode": 0, "Subscribers": [{ "SubscriberID": 456, "EmailAddress": "jane@example.com" }], "TotalSubscribers": 1500 }

Errors: 1 missing list, 2 missing segment, 3 invalid list, 4 invalid SearchField, 100005 database error (HTTP 500).

subscribers.search

Finds subscribers that match rules. POST /api.php.

Parameter Type Required Description
ListID int Yes
Operator string Yes and or or
RulesJSON string No Rules. Omit to search the whole list
RecordsPerRequest int No Default 25. Do not send 0
RecordsFrom int No Offset
OrderField string No A subscriber column or CustomField<ID>
OrderType string No ASC or DESC
OnlyTotal bool No Return only the count
curl https://app.emailmarketer.io/api.php \
  -d Command=subscribers.search \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d Operator=and \
  --data-urlencode RulesJSON='[[{"type":"fields","field_id":"EmailAddress","operator":"ends with","value":"@acme.com"}]]'
{ "Success": true, "ErrorCode": 0, "TotalSubscribers": 150, "Subscribers": [{ "SubscriberID": 456, "EmailAddress": "jane@example.com", "SubscriptionStatus": "Subscribed", "SubscriberTags": [], "Suppressed": false }] }

Errors: 1 missing ListID, 2 missing Operator, 3 list not found, 4 and 5 rule engine errors, 6 invalid RulesJSON, 7 query failed (retry).

Activity

Command Required Optional Returns
subscriber.activity.timeline ListID, SubscriberID ActivityType (default all), DateFrom, DateTo (YYYY-MM-DD), Page, Limit (1 to 100, default 20) Activities (Type, Subtype, Date, Title, Description), TotalActivities, HasMore
subscriber.get.activity SubscriberID, SubscriberListID none Activity (ActivityType, CampaignID, EmailID, ActivityDate)
subscriber.events ListID, plus SubscriberID or EmailAddress RecordsPerRequest (1 to 100, default 25), RecordsFrom, OrderField (event_created_at or event), OrderType Website events: TotalEvents, Events (event, event_created_at)

Examples:

# subscriber.activity.timeline
curl https://app.emailmarketer.io/api.php \
  -d Command=subscriber.activity.timeline \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d SubscriberID=456 \
  -d Limit=50

# subscriber.get.activity
curl https://app.emailmarketer.io/api.php \
  -d Command=subscriber.get.activity \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberID=456 \
  -d SubscriberListID=123

# subscriber.events
curl https://app.emailmarketer.io/api.php \
  -d Command=subscriber.events \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d SubscriberID=456

Import

subscribers.import.post

Starts a CSV import. POST /api/v1/subscribers.import. Errors array.

Parameter Type Required Description
ListID int Yes
AddToGlobalSuppressionList bool Yes Add the imported addresses to the account-wide suppression list
AddToSuppressionList bool Yes Add them to the list’s suppression list
UpdateDuplicates bool Yes Update contacts that are already on the list
TriggerActions bool Yes Run the list’s subscribe actions
Tags array Yes Tag names to add. Send [] for none
ImportFrom.CSV object Yes URL or Data, plus FieldTerminator, EscapedBy, MappedFields, and optional FieldEncloser
ImportStatusUpdateWebhookURL string No A public URL that gets status updates
{
  "ListID": 123, "AddToGlobalSuppressionList": false, "AddToSuppressionList": false,
  "UpdateDuplicates": true, "TriggerActions": false, "Tags": ["webinar"],
  "ImportFrom": { "CSV": { "URL": "https://example.com/contacts.csv", "FieldTerminator": ",", "EscapedBy": "\\", "FieldEncloser": "\"", "MappedFields": { "0": "EmailAddress", "1": "12" } } }
}
curl https://app.emailmarketer.io/api/v1/subscribers.import \
  -H "Content-Type: application/json" \
  -d '{
    "APIKey": "'"$EM_API_KEY"'",
    "ListID": 123, "AddToGlobalSuppressionList": false, "AddToSuppressionList": false,
    "UpdateDuplicates": true, "TriggerActions": false, "Tags": ["webinar"],
    "ImportFrom": { "CSV": { "URL": "https://example.com/contacts.csv", "FieldTerminator": ",", "EscapedBy": "\\", "FieldEncloser": "\"", "MappedFields": { "0": "EmailAddress", "1": "12" } } }
  }'

Returns {"ImportID":789,"ImportType":"async"}. Small files are imported at once and return "ImportType":"sync".

Errors: 1 missing ListID, 2 missing FieldTerminator, 4 to 7 a required flag is missing, 8 missing MappedFields, 9 to 12 a flag is invalid, 13 invalid MappedFields, 14 no source, 15 fields not mapped, 16 missing EscapedBy, 17 invalid mapping (with Reason), 18 the CSV URL could not be fetched or is not public, 19 list not found, 20 import could not be created, 21 missing Tags, 28 webhook URL is not public.

MappedFields maps CSV columns to fields. Keys are column numbers starting at 0. Values are EmailAddress or a custom field ID such as "12" (not CustomField12). Exactly one column must map to EmailAddress.

subscribers.import.get

Checks an import. GET /api/v1/subscribers.import with ListID and ImportID.

curl -G https://app.emailmarketer.io/api/v1/subscribers.import \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d ImportID=789
{ "ImportJob": { "ImportID": 789, "ImportStatus": "Completed", "TotalSubscribers": 1000, "TotalImported": 950, "TotalDuplicates": 30, "TotalFailed": 20 } }

ImportStatus is Not Ready, Pending, Importing, Completed or Failed. A job held for review adds Screening.

Errors: 1 missing ListID, 2 missing ImportID, 3 invalid ListID, 4 and 6 invalid ImportID, 5 list not found, 7 job not found.

Export

subscribers.export.post

Starts an export. POST /api/v1/subscribers.export. Errors array.

Parameter Type Required Description
ListID int Yes
RulesJSON array Yes Rules. Send [] for everyone
RulesOperator string Yes and or or
ExportFormat string Yes csv or json
FieldsToExport array Yes Fields to include
Target string No A status name or a segment ID
curl https://app.emailmarketer.io/api/v1/subscribers.export \
  -H "Content-Type: application/json" \
  -d '{ "APIKey": "'"$EM_API_KEY"'", "ListID": 123, "RulesJSON": [], "RulesOperator": "and", "ExportFormat": "csv", "FieldsToExport": ["EmailAddress"] }'

Returns {"ExportID":456}. Errors 1 to 12, including 7 invalid RulesJSON, 10 list not found, 11 invalid Target, 12 segment not found.

subscribers.export.get

GET /api/v1/subscribers.export with ListID, and ExportID for one job (omit it to list all jobs). Add Download=true to get the file once the job is Completed.

curl -G https://app.emailmarketer.io/api/v1/subscribers.export \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123 \
  -d ExportID=456
{ "ExportJob": { "ExportID": 456, "Status": "Completed", "SubmittedAt": "...", "FinishedAt": "...", "DownloadSize": 20480 } }

Errors: 1 missing ListID, 2 invalid ListID, 3 and 5 invalid ExportID, 4 list not found, 6 job not found, 7 file expired (HTTP 410).

Tags and journeys

Tagging subscribers is on Tags. Adding subscribers to journeys is on Journeys.