API reference

Suppression

Browse, check, import and remove suppressed email addresses on EmailMarketer.io, per list or account-wide, through the API.

A suppressed address gets no email. Addresses are suppressed when they hard bounce, complain, unsubscribe (if the list is set to suppress), or when you add them. All commands take APIKey and are sent to POST https://app.emailmarketer.io/api.php with Command.

Scopes and sources

Scope Applies to
PerList One list. Send ListID
AccountWide Every list in the account. Send ListID=0 or omit it
SystemWide Every account. Set by our team. You can read these entries but not remove them

SuppressionSource is User, Administrator, SPAM complaint, Hard Bounced or Unsubscribe.

With a ListID, browse and stats return everything that blocks sends to that list: the list’s own entries, account-wide entries and system-wide entries. Each address appears once, under its narrowest scope.

suppression.check

Checks up to 500 addresses before you send.

Parameter Type Required Description
EmailAddresses string One of the two A JSON array as a string: ["a@example.com","b@example.com"]
EmailAddressesBulk string One of the two One address per line
ListID int No Check against one list. 0 checks account-wide and system-wide entries only
curl https://app.emailmarketer.io/api.php \
  -d Command=suppression.check \
  -d APIKey="$EM_API_KEY" \
  --data-urlencode EmailAddresses='["a@example.com","b@example.com"]' \
  -d ListID=123
{
  "Success": true, "ErrorCode": 0, "ListID": 47, "TotalChecked": 1, "TotalFailed": 0,
  "Results": {
    "a@example.com": { "IsSuppressed": true, "IsPatternSuppressed": false, "MatchedScopes": [{ "Scope": "AccountWide", "SuppressionSource": "User", "Reason": "" }] }
  },
  "FailedEmailAddresses": []
}

Errors: 1 no input, 2 invalid JSON or no valid address, 4 invalid ListID, 5 more than 500 addresses, 6 lookup failed.

suppression.browse

Parameter Description
SearchPattern * is a wildcard
SuppressionSource Comma-separated sources
ListID 0 for account-wide, or one of your lists
StartFrom Offset. Default 0
RetrieveCount Default 100
IncludeCreatedOn Add the date each entry was created, in UTC
curl https://app.emailmarketer.io/api.php \
  -d Command=suppression.browse \
  -d APIKey="$EM_API_KEY" \
  -d SearchPattern="*@example.com"
{ "Success": true, "ErrorCode": 0, "TotalRecords": 12, "SuppressedEmails": { "user@example.com": { "SuppressionID": "1234", "EmailAddress": "user@example.com", "SuppressionSource": "Hard Bounced", "Reason": "...", "Scope": "AccountWide" } } }

SuppressedEmails is an object keyed by address, not an array. Errors: 1 invalid source, 4 invalid list, 100005 database error (HTTP 500).

suppression.stats

Counts by source. Takes the same SearchPattern, SuppressionSource and ListID filters as browse.

curl https://app.emailmarketer.io/api.php \
  -d Command=suppression.stats \
  -d APIKey="$EM_API_KEY" \
  -d ListID=123
{ "Success": true, "ErrorCode": 0, "Total": 1240, "BySource": { "Administrator": 5, "User": 312, "SPAM complaint": 14, "Hard Bounced": 871, "Unsubscribe": 38 } }

suppression.import

Adds addresses. POST /api/v1/suppression.import.

Parameter Description
EmailAddresses or EmailAddressesBulk As in suppression.check
SuppressionSource Default User
Reason Up to 250 characters
ListID 0 or omitted for account-wide
ReturnDetailedCounts Adds TotalAlreadySuppressed, TotalWhitelisted and TotalWriteFailed
curl https://app.emailmarketer.io/api.php \
  -d Command=suppression.import \
  -d APIKey="$EM_API_KEY" \
  --data-urlencode EmailAddresses='["a@example.com","b@example.com"]' \
  -d Reason="Asked not to be emailed"
{ "Success": true, "ErrorCode": 0, "TotalImported": 5, "TotalFailed": 0, "FailedEmailAddresses": [] }

Blank lines, duplicates and addresses on your allow list are skipped and not counted. Errors: 1 and 2 missing input or invalid JSON, 3 invalid source, 4 invalid list.

suppression.delete

Removes addresses from one scope.

Parameter Description
EmailAddress, EmailAddresses or EmailAddressesBulk One address, a JSON array or one per line
ListID Removes only entries in that exact scope
curl https://app.emailmarketer.io/api.php \
  -d Command=suppression.delete \
  -d APIKey="$EM_API_KEY" \
  -d EmailAddress=a@example.com \
  -d ListID=123
{ "Success": true, "ErrorCode": 0, "StillSuppressed": [{ "EmailAddress": "a@example.com", "Scopes": ["AccountWide"] }] }

StillSuppressed lists addresses that are still blocked by another scope. Bulk calls add TotalDeleted, TotalFailed and FailedEmailAddresses. Errors: 1 no input, 2 invalid address, not suppressed, or invalid JSON, 4 invalid list.

Transactional email

Transactional sends to a suppressed address are refused with HTTP 409, error 14. Over SMTP, suppressed recipients are removed from the message. See Send email.