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.