SpamHero's RESTful API can be used to safely and efficiently integrate your SpamHero account management with external systems.
If you are currently a SpamHero customer, you can set up API keys and get started right away at Tools > API in the control panel.
If you are looking at getting started with SpamHero, Welcome! To get started with the API, you'll first need to sign up for a free 30-day trial.
The SpamHero API uses basic HTTP authentication. Your API key is the "username", the "password" is left blank. Most programming languages can add the correct header for you, check the examples below.
Each API key is limited to 60 requests per minute. This limitation is not URL specific, so once 60 API requests of any kind have been made within one minute, further requests will be throttled. If it is suspected that the API is being abused (accessed with high frequency for extended periods of time, use of multiple keys to intentionally circumvent throttling, etc.), your API keys may be revoked.
There are 3 API calls you'll want to make to set up service for a new domain. The first one is /api/reseller/order (or, /api/order if you are not a reseller).
Once your order has been placed with this API request, you'll want to call /api/order-check periodically until you've confirmed the order has been complete. (normally takes a few minutes).
Finally, you'll need to know when the required MX records are propagated, and what they are so you can update the domain's MX records. For this, you'll use /api/get-required-mx. View the documentation for each request for details.
GET
/ POST
A basic request that does nothing, so you can test authorizing via the API.
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | Message stating that your request was authorized |
curl "https://www.spamhero.com/api" \
-u YOUR_API_KEY_HERE:
POST
Order spam filtering services for an additional domain (non-reseller account)
Parameter | Format | Description |
new_domain* | String | Domain name to order |
billing_schedule* | ['annual', 'monthly'] | 'annual' or 'monthly' (takes effect after free trial) |
plan* | ['lite', 'basic', 'standard', 'enterprise'] | Spam filtering plan for the new domain |
promo_code | String |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
order_code | String | An ID that can be used to track the status of your order. |
message | String | A confirmation that your order has been placed |
curl "https://www.spamhero.com/api/order" \
-u YOUR_API_KEY_HERE: \
-d new_domain=SOME_VALUE \
-d billing_schedule=SOME_VALUE \
-d plan=SOME_VALUE
POST
Order spam filtering services for an additional domain (reseller account)
Parameter | Format | Description |
new_domain* | String | Domain name to order |
billing_schedule* | ['annual', 'monthly'] | 'annual' or 'monthly' (takes effect after free trial) |
promo_code | String | |
sub_account_id | Integer | sub-account ID to place the new domain. Leave blank to use a new sub-account. |
custom | String | String to associate with this sub-account for your own purposes. (up to 250 characters) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
order_code | String | An ID that can be used to track the status of your order. |
message | String | A confirmation that your order has been placed |
curl "https://www.spamhero.com/api/reseller/order" \
-u YOUR_API_KEY_HERE: \
-d new_domain=SOME_VALUE \
-d billing_schedule=SOME_VALUE
POST
Cancel spam filtering services for a domain.
Parameter | Format | Description |
domain* | String | Domain to cancel services for. |
confirm_domain_to_cancel* | String | Domain to cancel services for (repeated for confirmation purposes). |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | A confirmation that the domain has been cancelled. |
curl "https://www.spamhero.com/api/cancel-service" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d confirm_domain_to_cancel=SOME_VALUE
GET
Check the status of an order
Parameter | Format | Description |
order_code* | String | Order code to check on. Provided when the domain was originally ordered via the API. |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
status | ['processing', 'complete', 'error'] | Status of the order in question. |
domain | String | Domain name that was ordered |
curl "https://www.spamhero.com/api/order-check?order_code=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
GET
Confirm that the MX records for your domain are ready for use, and return the required MX records
Parameter | Format | Description |
domain* | String | Domain to get required MX records for (not required if using a domain-specific API key) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
mx_ready | Boolean |
true if the MX records for your domain have been fully provisioned, otherwise false .
|
required_mx_array* | Array |
Contains the required MX records for your domain. Provided only when "mx_ready" is true . The array keys indicate the required permission levels.
|
required_mx_text* | String |
Contains the required MX records for your domain. Provided only when "mx_ready" is true . Plain text display for human reading.
|
curl "https://www.spamhero.com/api/get-required-mx?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
GET
Get a list of all domains on your account
Parameter | Format | Description |
include_aliases (or 'alias') | String (default: no) | "yes" if you want to also get a list of domain aliases |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
domains | Array | Array containing domains belonging to your account |
aliases* | Array | Multi-dimensional array, with keys named after each domain belonging to your account, pointing to an array of aliases belonging to the domain. (example: [myDomain.com=>[aliasA.com], myDomain2.com=>[aliasB.com,aliasC.com]]) |
curl "https://www.spamhero.com/api/domains" \
-u YOUR_API_KEY_HERE:
GET
Check the MX records for a domain
Parameter | Format | Description |
domain* | String | Domain to check MX records for (not required if using a domain-specific API key) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
result | ['correct', 'incorrect'] | |
details | String | Details about the mx record check result |
curl "https://www.spamhero.com/api/mx-check?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
POST
Suspend service for a sub-account or domain (API for resellers only)
Parameter | Format | Description |
suspend_domain | String | Domain name to suspend services for. (Required if 'suspend_subaccount' is not given) |
suspend_subaccount | String | Sub-account to suspend services for. (Either the sub-account ID, or the domain name of one of the domains on the sub-account. Required if 'suspend_domain' is not given) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | A confirmation that services for the domain have been suspended. |
curl "https://www.spamhero.com/api/suspend-service" \
-u YOUR_API_KEY_HERE: \
-X POST
POST
Reactivate service for a sub-account or domain (API for resellers only)
Parameter | Format | Description |
reactivate_domain | String | Domain name to reactivate services for. (Required if 'reactivate_subaccount' is not given) |
reactivate_subaccount | String | Sub-account to reactivate services for. (Either the sub-account ID, or the domain name of one of the domains on the sub-account. Required if 'reactivate_domain' is not given) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | A confirmation that services for the domain have been reactivated. |
curl "https://www.spamhero.com/api/reactivate-service" \
-u YOUR_API_KEY_HERE: \
-X POST
GET
List current subscriptions, with their child subscriptions, current status, and billing information.
Parameter | Format | Description |
search | String | Return only subscriptions for domains that matches a search (fully or partially) |
per_page (or 'limit') | Integer (default: 1000) | Maximum number of subscriptions to list at once (max 1,000) |
page | String (default: 1) | Desired page number |
offset | Integer |
Offset for getting subscriptions. Can be used in combination with (or instead of) page parameter.
|
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
subscriptions | Array | The array of subscriptions that match given criteria. Contains: domain, status, activated_date, plan, next_bill_date, custom, billing_schedule, rate, total, child_subscriptions (Array containing: "description" and "rate" for each child subscription) |
total | Integer | Total count of subscriptions that match given criteria |
pagination | String | Human readable pagination details |
total_pages | Integer | Total number of pages |
links | Array | An array containing links to the first page, last page, next page, and previous page of records ("next" and "previous" will only appear in the array when they are applicable). These URLs are also available in the return headers. |
curl "https://www.spamhero.com/api/subscriptions/list" \
-u YOUR_API_KEY_HERE:
GET
List invoices for your account. Also shows your account's current balance
Parameter | Format | Description |
search_domain | String | Get only invoices related to a domain |
search_custom | String | Get only invoices related to a domain with matching custom value |
start_date | YYYY-MM-DD (default: 60 days ago) | Get invoices only after this date. |
end_date | YYYY-MM-DD (default: today) | Get invoices only before this date. |
per_page (or 'limit') | Integer (default: 1000) | Maximum number of invoices to list at once (max 1,000) |
page | Integer (default: 1) | Desired page number |
offset | Integer |
Offset for getting invoices. Can be used in combination with (or instead of) page parameter.
|
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
invoices | Array | The array of invoices, containing: date, total, status, and invoice_items (an array containing: description, count, subtotal, custom, and domain for each invoice item) |
total | Integer | Total number of invoices that match given criteria |
pagination | String | Human readable pagination details |
total_pages | Integer | Total number of pages |
links | Array | An array containing links to the first page, last page, next page, and previous page of records ("next" and "previous" will only appear in the array when they are applicable). These URLs are also available in the return headers. |
balance_due | String | The current unpaid balance due on your account |
balance_forward | String | The amount of unused credit on your account |
curl "https://www.spamhero.com/api/billing/invoices" \
-u YOUR_API_KEY_HERE:
GET
List recent payments to your account.
Parameter | Format | Description |
start_date | YYYY-MM-DD (default: 60 days ago) | Get payments only after this date. |
end_date | YYYY-MM-DD (default: today) | Get payments only before this date. |
per_page (or 'limit') | Integer (default: 1000) | Maximum number of payments to list at once (max 1,000) |
page | Integer (default: 1) | Desired page number |
offset | Integer |
Offset for getting payments. Can be used in combination with (or instead of) page parameter.
|
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
payments | Array | The array of payments |
total | Integer | Total number of payments that match given criteria |
pagination | String | Human readable pagination details |
total_pages | Integer | Total number of pages |
links | Array | An array containing links to the first page, last page, next page, and previous page of records ("next" and "previous" will only appear in the array when they are applicable). These URLs are also available in the return headers. |
curl "https://www.spamhero.com/api/billing/payments" \
-u YOUR_API_KEY_HERE:
POST
Set the custom value for a given sub-account (For resellers only)
Parameter | Format | Description |
domain* | String | Domain belonging to the sub-account to associate this custom variable with (not required if using a domain-specific API key) |
custom* | String | String to associate with this sub-account for your own purposes. (up to 250 characters) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | Message about the success of the request |
curl "https://www.spamhero.com/api/sub-account/set-custom" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d custom=SOME_VALUE
POST
Create a domain alias
Parameter | Format | Description |
domain* | String | Domain to create alias for (not required if using a domain-specific API key) |
alias* | String | The alias you want to add |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | A message reporting on the success of the alias creation |
mx_record_notice | String | A message concerning the current state MX records for the alias domain. |
curl "https://www.spamhero.com/api/alias/add" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d alias=SOME_VALUE
POST
Delete a domain alias
Parameter | Format | Description |
domain* | String | Domain to delete alias from (not required if using a domain-specific API key) |
delete_alias* | String | The alias you want to delete |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | A message reporting on the success of the alias deletion |
curl "https://www.spamhero.com/api/alias/delete" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d delete_alias=SOME_VALUE
GET
Check the MX records for a domain alias
Parameter | Format | Description |
domain* | String | Domain to check alias for (not required if using a domain-specific API key) |
alias* | String | The alias to check MX records for |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
result | ['correct', 'incorrect'] | |
details | String | Details about the mx record check result |
curl "https://www.spamhero.com/api/alias/mx-check?domain=SOME_VALUE&alias=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
GET
Get a list of all approved email recipients for a domain (up to 1,000 at a time)
Parameter | Format | Description |
domain* | String | Domain to list email addresses for (not required if using a domain-specific API key) |
type | ['approved', 'detected', 'all'] (default: all) | Type of recipient to list |
per_page (or 'limit') | Integer (default: 1000) | Maximum number of emails to show (up to 1,000) |
page | String (default: 1) | Desired page number |
search | String | Return only email address that match a search (fully or partially) |
offset | Integer |
Offset for records obtained. Can be used in combination with (or instead of) page parameter.
|
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
email_prefixes | Array | Array containing approved email recipients for a domain |
total | Integer | Total count of email recipients that match given type and search |
pagination | String | Human readable pagination details |
total_pages | Integer | Total number of pages |
links | Array | An array containing links to the first page, last page, next page, and previous page of records ("next" and "previous" will only appear in the array when they are applicable). These URLs are also available in the return headers. |
curl "https://www.spamhero.com/api/email-recipient/list?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
POST
Add one or more email recipients to a domain
Parameter | Format | Description |
domain* | String | Domain that should be affected (not required if using a domain-specific API key) |
addresses* (or 'address' or 'email' or 'emails') | String | A comma separated list of email addresses to add as recipients |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
added | Integer | Number of email recipients added |
already_existed | Integer | Number of email recipients that were not added because they already existed |
curl "https://www.spamhero.com/api/email-recipient/add" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d addresses=SOME_VALUE
POST
Mark email recipients as invalid (mail for these recipients will be rejected even if your catch-all is enabled)
Parameter | Format | Description |
domain* | String | Domain that should be affected (not required if using a domain-specific API key) |
addresses* (or 'address' or 'email' or 'emails') | String | A comma separated list of email addresses to mark invalid |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
marked_invalid | String | Number of email recipients marked invalid |
already_invalid | Integer | Number of email recipients that were already marked invalid |
could_not_mark_quarantine_users | String | Array of email recipients that could not be marked invalid because they belong to quarantine users (remove the quarantine users first) |
could_not_mark_account_contacts | String | Array of email recipients that could not be marked invalid because they belong to account contacts (remove the account contacts first) |
curl "https://www.spamhero.com/api/email-recipient/invalid" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d addresses=SOME_VALUE
POST
Delete email recipients (mail for these recipients will be rejected unless your catch-all is enabled)
Parameter | Format | Description |
domain* | String | Domain that should be affected (not required if using a domain-specific API key) |
addresses* (or 'address' or 'email' or 'emails') | String | A comma separated list of email addresses to delete |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
deleted | String | Number of email recipients deleted |
not_found | String | Number of email recipients that did not exist |
could_not_delete_quarantine_users | String | Array of email recipients that could not be deleted because they belong to quarantine users (remove the quarantine users first) |
could_not_delete_account_contacts | String | Array of email recipients that could not be deleted because they belong to account contacts (remove the account contacts first) |
curl "https://www.spamhero.com/api/email-recipient/delete" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d addresses=SOME_VALUE
GET
List existing quarantine users
Parameter | Format | Description |
domain* | String | Domain to show quarantine users for (not required if using a domain-specific API key) |
search | String | Return only quarantine users with an email address that matches a search (fully or partially) |
per_page (or 'limit') | Integer (default: 1000) | Maximum number of quarantine users to list at once (max 1,000) |
page | String (default: 1) | Desired page number |
offset | Integer |
Offset for getting quarantine users. Can be used in combination with (or instead of) page parameter.
|
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
quarantine_users | Array | Quarantine users that match given criteria |
total | Integer | Total count of quarantine users that match given criteria |
pagination | String | Human readable pagination details |
total_pages | Integer | Total number of pages |
links | Array | An array containing links to the first page, last page, next page, and previous page of records ("next" and "previous" will only appear in the array when they are applicable). These URLs are also available in the return headers. |
curl "https://www.spamhero.com/api/quarantine-user/list?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
POST
Add a quarantine user
Parameter | Format | Description |
domain* | String | Domain to add the quarantine user to (not required if using a domain-specific API key) |
email* | String | email address for quarantine user (for multiple, use a comma separated list. However, take note that all emails provided will be attached to the same quarantine user. For multiple quarantine users, use multiple API requests.) |
agree_to_cost | ['yes', 'no'] | Required if you are not a reseller. Pass 'yes' to agree to the $1 per month cost. |
name | String | Name of quarantine user |
timezone | String | Timezone to be used for quarantine user (for domain default, skip this). See supported timezones |
report_address | String | Address to send quarantine reports to. Skip this to default to the quarantine user's email address. |
report_frequency | ['never', 'custom', 'hourly', 'daily', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'] | Address to send quarantine reports to. Skip this to default your domain's default report frequency. |
report_time | HH:MM AM/PM | Required if 'report_frequency' is given and set to something other than 'never', 'custom', or 'hourly'. |
report_custom_schedule | String | Required if 'report_frequency' is set to 'custom'. Pass the name of the custom schedule you would like to use. |
send_password | ['yes', 'no'] (default: yes) | 'yes' to send an email to the quarantine user to set up their password. 'no' to skip the email. |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | Message about the success of the request |
curl "https://www.spamhero.com/api/quarantine-user/add" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d email=SOME_VALUE
POST
Edit an existing quarantine user
Parameter | Format | Description |
domain* | String | Domain to add the quarantine user to (not required if using a domain-specific API key) |
email* | String | The email address for the quarantine user you want to edit |
name | String | Name of quarantine user |
timezone | String | Timezone to be used for quarantine user (for domain default, skip this). See supported timezones |
report_address | String | Address to send quarantine reports to. Skip this to default to the quarantine user's email address. |
report_frequency | ['never', 'custom', 'hourly', 'daily', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'] | Address to send quarantine reports to. Skip this to default your domain's default report frequency. |
report_time | HH:MM AM/PM | Required if 'report_frequency' is given and set to something other than 'never', 'custom', or 'hourly'. |
report_custom_schedule | String | Required if 'report_frequency' is set to 'custom'. Pass the name of the custom schedule you would like to use. |
send_password | ['yes', 'no'] (default: no) | 'yes' to send an email to the quarantine user to set up their password. 'no' to skip the email. |
new_email | String | Set a new email address for this quarantine user. |
confirm_verified_email_reset | String | Required when changing an account contact's email address when the account contact has verified emails. Set to 'yes' to confirm that these verified emails will be reset when you change their login email. |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | Message about the success of the request |
curl "https://www.spamhero.com/api/quarantine-user/edit" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d email=SOME_VALUE
POST
Delete a quarantine user
Parameter | Format | Description |
domain* | String | Domain to delete the quarantine user from (not required if using a domain-specific API key) |
quarantine_user_to_delete* | String | email address to identify the quarantine user to delete |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | Message about the success of the request |
curl "https://www.spamhero.com/api/quarantine-user/delete" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d quarantine_user_to_delete=SOME_VALUE
GET
List existing account contacts
Parameter | Format | Description |
search | String | Return only account contacts with an email address that matches a search (fully or partially) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
account_contacts | Array | Account contacts that match given criteria |
total | Integer | Total count of account contacts that match given criteria |
curl "https://www.spamhero.com/api/account-contact/list" \
-u YOUR_API_KEY_HERE:
GET
List existing account contacts an account belonging to your client
Parameter | Format | Description |
domain* | String | Domain that belongs to the client account you want to list account contacts for. (not required if using a domain-specific API key) |
search | String | Return only account contacts with an email address that matches a search (fully or partially) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
account_contacts | Array | Account contacts that match given criteria |
total | Integer | Total count of account contacts that match given criteria |
curl "https://www.spamhero.com/api/account-contact/reseller/list?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
POST
Add an account contact to one of your client's accounts
Parameter | Format | Description |
domain* | String | Domain that belongs to the client account you want to add this account contact to. (not required if using a domain-specific API key) |
email* | String | email address for account contact (for multiple, use a comma separated list. However, take note that all emails provided will be attached to the same quarantine user. For multiple quarantine users, use multiple API requests.) |
name | String | Name of account contact |
timezone | String | Timezone to be used for account contact (for account default, skip this). See supported timezones |
send_password | ['yes', 'no'] (default: yes) | 'yes' to send an email (with your private branding) to the account contact to set up their password. 'no' to skip the email. |
account_owner | ['yes', 'no'] (default: no) | Is this user an account owner (of your client's account)? |
billing_access | ['yes', 'no'] (default: yes) | Does this user get access to billing related pages (to your client's account)? |
tech_access | ['yes', 'no'] (default: yes) | Does this user get access to technical pages (filter settings, etc. of your client's account)? |
api_auto_login | ['yes', 'no'] | Should the API use this user when generating auto-login links? |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | Message about the success of the request |
curl "https://www.spamhero.com/api/account-contact/reseller/add" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d email=SOME_VALUE
POST
Edit an account contact belonging to one of your client's accounts
Parameter | Format | Description |
domain* | String | Domain that belongs to the client account for the target account contact. (not required if using a domain-specific API key) |
email* | String | An email address that belongs to the account contact you want to edit |
new_email | String | New email address(es) for account contact (REPLACES current email address) |
name | String | New Name of account contact |
timezone | String | New Timezone to be used for account contact (for account default, skip this). See supported timezones |
send_password | ['yes', 'no'] (default: no) | 'yes' to send an email (with your private branding) to the account contact to set up their password. 'no' to skip the email. |
account_owner | ['yes', 'no'] | Is this user an account owner (of your client's account)? |
billing_access | ['yes', 'no'] | Does this user get access to billing related pages (to your client's account)? |
tech_access | ['yes', 'no'] | Does this user get access to technical pages (filter settings, etc. of your client's account)? |
api_auto_login | ['yes', 'no'] | Should the API use this user when generating auto-login links for your client? |
confirm_verified_email_reset | String | Required when changing an account contact's email address when the account contact has verified emails. Set to 'yes' to confirm that these verified emails will be reset when you change their login email. |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | Message about the success of the request |
curl "https://www.spamhero.com/api/account-contact/reseller/edit" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d email=SOME_VALUE
POST
Delete an account contact from one of your client's accounts.
Parameter | Format | Description |
domain* | String | Domain that belongs to the client account for the target account contact. (not required if using a domain-specific API key) |
account_contact_to_delete* | String | An email address belonging to the account contact you want to delete. |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | Message about the success of the request |
curl "https://www.spamhero.com/api/account-contact/reseller/delete" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d account_contact_to_delete=SOME_VALUE
POST
Add one or more approved senders
Parameter | Format | Description |
domain* | String | Domain that should be affected (not required if using a domain-specific API key) |
senders* (or 'address' or 'email' or 'emails' or 'addresses') | String | A comma separated list of email addresses / domains / IP addresses to add as approved recipients |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
added | Integer | Number of approved senders added |
already_existed | Integer | Number of approved senders that were not added because they already existed |
curl "https://www.spamhero.com/api/sender/approved/add" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d senders=SOME_VALUE
GET
List existing approved senders
Parameter | Format | Description |
domain* | String | Domain to show approved senders for (not required if using a domain-specific API key) |
search | String | Return only approved senders with an email address / domain / IP address that matches a search (fully or partially) |
per_page (or 'limit') | Integer (default: 1000) | Maximum number of approved senders to list at once (max 1,000) |
page | String (default: 1) | Desired page number |
offset | Integer |
Offset for getting approved senders. Can be used in combination with (or instead of) page parameter.
|
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
approved_senders | Array | Approved senders that match given criteria |
total | Integer | Total count of approved senders that match given criteria |
pagination | String | Human readable pagination details |
total_pages | Integer | Total number of pages |
links | Array | An array containing links to the first page, last page, next page, and previous page of records ("next" and "previous" will only appear in the array when they are applicable). These URLs are also available in the return headers. |
curl "https://www.spamhero.com/api/sender/approved/list?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
POST
Delete an approved sender
Parameter | Format | Description |
domain* | String | Domain to delete the approved sender from (not required if using a domain-specific API key) |
approved_sender_to_delete* | String | Full email address / domain / IP address of the approved sender you want to delete. (For multiple deletes, pass an array or comma separated list) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | Message about the success of the request |
curl "https://www.spamhero.com/api/sender/approved/delete" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d approved_sender_to_delete=SOME_VALUE
POST
Add one or more blocked senders
Parameter | Format | Description |
domain* | String | Domain that should be affected (not required if using a domain-specific API key) |
senders* (or 'address' or 'email' or 'emails' or 'addresses') | String | A comma separated list of email addresses / domains / IP addresses to add as blocked recipients |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
added | Integer | Number of blocked senders added |
already_existed | Integer | Number of blocked senders that were not added because they already existed |
curl "https://www.spamhero.com/api/sender/blocked/add" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d senders=SOME_VALUE
GET
List existing blocked senders
Parameter | Format | Description |
domain* | String | Domain to show blocked senders for (not required if using a domain-specific API key) |
search | String | Return only blocked senders with an email address / domain / IP address that matches a search (fully or partially) |
per_page (or 'limit') | Integer (default: 1000) | Maximum number of blocked senders to list at once (max 1,000) |
page | String (default: 1) | Desired page number |
offset | Integer |
Offset for getting blocked senders. Can be used in combination with (or instead of) page parameter.
|
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
blocked_senders | Array | blocked senders that match given criteria |
total | Integer | Total count of blocked senders that match given criteria |
pagination | String | Human readable pagination details |
total_pages | Integer | Total number of pages |
links | Array | An array containing links to the first page, last page, next page, and previous page of records ("next" and "previous" will only appear in the array when they are applicable). These URLs are also available in the return headers. |
curl "https://www.spamhero.com/api/sender/blocked/list?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
POST
Delete a blocked sender
Parameter | Format | Description |
domain* | String | Domain to delete the blocked sender from (not required if using a domain-specific API key) |
blocked_sender_to_delete* | String | Full email address / domain / IP address of the blocked sender you want to delete. (For multiple deletes, pass an array or comma separated list) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | Message about the success of the request |
curl "https://www.spamhero.com/api/sender/blocked/delete" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d blocked_sender_to_delete=SOME_VALUE
GET
Count messages received for a domain over a given date range.
Parameter | Format | Description |
domain* | String | Domain to count messages for (not required if using a domain-specific API key) |
start_date | YYYY-MM-DD (default: 90 days ago) | Count messages only after this date. |
end_date | YYYY-MM-DD (default: Today) | Count messages only before this date. |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
date_range | String | Date range used for stats |
total | Integer | Number of messages received for your domain over the given time period |
clean | Integer | Number of clean messages received for your domain over the given time period |
spam | Integer | Number of spam messages received for your domain over the given time period |
false_positives | Integer | Number of false positives reported for your domain over the given time period |
missed_spam | Integer | Number of missed spam reported for your domain over the given time period |
effectiveness | String | Effectiveness of the spam filter over the given time period |
outbound_total | Integer | Total number of outbound messages that were attempted |
outbound_clean | Integer | Number of messages sent outward for your domain |
outbound_spam | Integer | Number of messages prevented from being sent for your domain |
curl "https://www.spamhero.com/api/email-stats?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
GET
Count the number of inbound messages that meet given criteria. This request accepts the same parameters that the quarantine plus page does, so you can check your browser's devtools on the quarantine plus page for what parameters are passed for specific searches. Only counts messages from the last 7-30 days, depending on your plan. To get general email stats for a more broad time period, you can use "email-stats" instead.
Parameter | Format | Description |
domain* | String | Domain to count messages for (not required if using a domain-specific API key) |
recipient | String | Count messages delivered to a specific recipient |
sender | String | Count messages delivered from a specific sender |
start_date | YYYY-MM-DD HH:MM AM/PM | Count messages only after this date. |
end_date | YYYY-MM-DD HH:MM AM/PM | Count messages only before this date. |
status | String (default: all-spam) | Possible values: 'all', 'all-and-deleted', 'all-clean', 'delivered', 'pending', 'delivered-delayed', 'failed', 'pending-failed', 'false-positive', 'whitelist', 'all-spam', 'missed-spam', 'deleted-spam', 'all-spam-deleted' |
sender_name | String | Sender name |
sender_email | String | |
sender_messageid | String | Message ID |
domainid | String | |
sender_host_alignment | String | |
deepfilter_hit | String |
Deep filter reason Possible values: 'UnsafeAttachment-suspicious' (Suspicious attachment), 'DmarcPolicy-fail' (DMARC failure) |
filter_rule_id | String | Filter rule ID |
deepfilter_rule_id | String | Deep filter rule ID |
msg_group | String | Message selection ID |
fingerprint | String | |
mid | String | Message Record ID |
recipient | String | To |
recipient_email | String | |
actual_recipient_email | String | Recipient |
subject | String | |
attachment_list | String | Attachment file name |
country | String |
Sender country Possible values: 'af' (Afghanistan), 'ax' (Aland Islands), 'al' (Albania), 'dz' (Algeria), 'ad' (Andorra), 'ao' (Angola), 'ai' (Anguilla), 'ag' (Antigua and Barbuda), 'ar' (Argentina), 'am' (Armenia), 'aw' (Aruba), 'ap' (Asia/Pacific Region), 'au' (Australia), 'at' (Austria), 'az' (Azerbaijan), 'bs' (Bahamas), 'bh' (Bahrain), 'bd' (Bangladesh), 'bb' (Barbados), 'by' (Belarus), 'be' (Belgium), 'bz' (Belize), 'bj' (Benin), 'bm' (Bermuda), 'bt' (Bhutan), 'bo' (Bolivia), 'bq' (Bonaire, Saint Eustatius and Saba), 'ba' (Bosnia and Herzegovina), 'bw' (Botswana), 'br' (Brazil), 'vg' (British Indian Ocean Territory), 'bn' (Brunei Darussalam), 'bg' (Bulgaria), 'bf' (Burkina Faso), 'bi' (Burundi), 'kh' (Cambodia), 'cm' (Cameroon), 'ca' (Canada), 'cv' (Cape Verde), 'ky' (Cayman Islands), 'cf' (Central African Republic), 'td' (Chad), 'cl' (Chile), 'cn' (China), 'cx' (Christmas Island), 'cc' (Cocos (Keeling) Islands), 'co' (Colombia), 'km' (Comoros), 'cg' (Congo (Brazzaville)), 'cd' (Congo, The Democratic Republic of the), 'ck' (Cook Islands), 'cr' (Costa Rica), 'ci' (Cote D'Ivoire), 'hr' (Croatia), 'cu' (Cuba), 'cw' (Curacao), 'cy' (Cyprus), 'cz' (Czech Republic), 'dk' (Denmark), 'dj' (Djibouti), 'dm' (Dominica), 'do' (Dominican Republic), 'ec' (Ecuador), 'eg' (Egypt), 'sv' (El Salvador), 'gq' (Equatorial Guinea), 'er' (Eritrea), 'ee' (Estonia), 'et' (Ethiopia), 'eu' (Europe (Country unknown)), 'fk' (Falkland Islands (Malvinas)), 'fo' (Faroe Islands), 'fj' (Fiji), 'fi' (Finland), 'fr' (France), 'gf' (French Guiana), 'pf' (French Polynesia), 'tf' (French Southern Territories), 'ga' (Gabon), 'gm' (Gambia), 'ge' (Georgia), 'de' (Germany), 'gh' (Ghana), 'gi' (Gibraltar), 'gr' (Greece), 'gl' (Greenland), 'gd' (Grenada), 'gp' (Guadeloupe), 'gu' (Guam), 'gt' (Guatemala), 'gg' (Guernsey), 'gn' (Guinea), 'gw' (Guinea-Bissau), 'gy' (Guyana), 'ht' (Haiti), 'hn' (Honduras), 'hk' (Hong Kong), 'hu' (Hungary), 'is' (Iceland), 'in' (India), 'id' (Indonesia), 'ir' (Iran), 'iq' (Iraq), 'ie' (Ireland), 'im' (Isle of Man), 'il' (Israel), 'it' (Italy), 'jm' (Jamaica), 'jp' (Japan), 'je' (Jersey), 'jo' (Jordan), 'kz' (Kazakhstan), 'ke' (Kenya), 'ki' (Kiribati), 'kp' (Korea, North), 'kr' (Korea, South), 'kv' (Kosovo), 'kw' (Kuwait), 'kg' (Kyrgyzstan), 'la' (Laos), 'lv' (Latvia), 'lb' (Lebanon), 'ls' (Lesotho), 'lr' (Liberia), 'ly' (Libya), 'li' (Liechtenstein), 'lt' (Lithuania), 'lu' (Luxembourg), 'mo' (Macau), 'mk' (Macedonia), 'mg' (Madagascar), 'mw' (Malawi), 'my' (Malaysia), 'mv' (Maldives), 'ml' (Mali), 'mt' (Malta), 'mh' (Marshall Islands), 'mq' (Martinique), 'mr' (Mauritania), 'mu' (Mauritius), 'yt' (Mayotte), 'mx' (Mexico), 'fm' (Micronesia), 'md' (Moldova), 'mc' (Monaco), 'mn' (Mongolia), 'ms' (Monserrat), 'me' (Montenegro), 'ma' (Morocco), 'mz' (Mozambique), 'mm' (Myanmar), 'na' (Namibia), 'nr' (Nauru), 'np' (Nepal), 'nl' (Netherlands), 'nc' (New Caledonia), 'nz' (New Zealand), 'ni' (Nicaragua), 'ne' (Niger), 'ng' (Nigeria), 'nu' (Niue), 'nf' (Norfolk Island), 'mp' (Northern Mariana Islands), 'no' (Norway), 'om' (Oman), 'pk' (Pakistan), 'pw' (Palau), 'ps' (Palestinian Territories), 'pa' (Panama), 'pg' (Papua New Guinea), 'py' (Paraguay), 'pe' (Peru), 'ph' (Phillipines), 'pn' (Pitcairn Islands), 'pl' (Poland), 'pt' (Portugal), 'pr' (Puerto Rico), 'qa' (Qatar), 're' (Reunion), 'ro' (Romania), 'ru' (Russia), 'rw' (Rwanda), 'sh' (Saint Helena), 'lc' (Saint Lucia), 'mf' (Saint Martin), 'pm' (Saint Pierre and Miquelon), 'vc' (Saint Vincent and the Grenadines), 'bl' (Saint-Barthelemy), 'ws' (Samoa), 'as' (Samoa, American), 'sm' (San Marino), 'sa' (Saudi Arabia), 'sn' (Senegal), 'rs' (Serbia), 'sc' (Seychelles), 'sl' (Sierra Leone), 'sg' (Singapore), 'sx' (Sint Maarten), 'sk' (Slovakia), 'si' (Slovenia), 'sb' (Solomon Islands), 'so' (Somalia), 'za' (South Africa), 'gs' (South Georgia and the South Sandwich Islands), 'ss' (South Sudan), 'es' (Spain), 'lk' (Sri Lanka), 'kn' (St. Kitts and Nevis), 'sd' (Sudan), 'sr' (Suriname), 'sj' (Svalbard and Jan Mayen Islands), 'sz' (Swaziland), 'se' (Sweden), 'ch' (Switzerland), 'sy' (Syria), 'tw' (Taiwan), 'tj' (Tajikistan), 'tz' (Tanzania), 'th' (Thailand), 'tl' (Timor Leste (West)), 'tg' (Togo), 'tk' (Tokelau), 'to' (Tonga), 'tt' (Trinidad and Tobago), 'tn' (Tunisia), 'tr' (Turkey), 'tm' (Turkmenistan), 'tc' (Turks and Caicos Islands), 'tv' (Tuvalu), 'ug' (Uganda), 'ua' (Ukraine), 'ae' (United Arab Emirates), 'gb' (United Kingdom), 'um' (United States Minor Outlying Islands), 'us' (United States), 'XX' (Unknown), 'uy' (Uruguay), 'uz' (Uzbekistan), 'vu' (Vanuatu), 'va' (Vatican City State), 've' (Venezuela), 'vn' (Vietnam), 'vi' (Virgin Islands (US)), 'wf' (Wallis and Futuna), 'eh' (Western Sahara), 'st' (Western Sahara), 'ye' (Yemen), 'zm' (Zambia), 'zw' (Zimbabwe) |
date | String | YYYY-MM-DD |
header_date | String | |
reason | String | Spam category |
master | String | Search Searches 'sender' or 'recipient' or 'subject' or 'envelope_sender' or 'recipient_email' or 'filter_rule_id' or 'deepfilter_rule_id' |
spf_result | String | |
envelope_sender | String | Return-Path |
sender | String | From |
filter_details | String |
Spam category Possible values: 'Filtering disabled' (Filtering disabled), 'policy_geo' (Geographic Policy), 'Custom Filter' (Custom Filter), 'blocked sender' (Blocked sender), 'policy:foreignchars' (Non-English character set), 'policy:badheaders' (Invalid headers), 'clamav' (Virus), 'policy:UnsafeAttachment' (Unsafe attachment), 'policy:CorruptArchive' (Corrupt and password protected archives), 'url blacklist' (URL blacklist), 'htma3' (HTML Redirect Attachment), 'htma4' (HTML Javascript Attachment), 'policy:missedspam_autoblocksender' (Confirmed sender from missed spam report), 'policy:SPF' (SPF sender authentication), 'Sender alignment mismatch' (Sender alignment mismatch), 'Edge Rule' (Edge Rule), 'Possible Spam Source' (Possible Spam Source), 'Confirmed Spam Source' (Confirmed Spam Source), 'Adult/Porn/Dating' (Dating/Adult/Porn), 'DeepRush' (DeepRush), 'Get-Rich Quick' (Get-Rich Quick), 'Insurance' (Insurance), 'Likely Spam Source' (Likely Spam Source), 'Loans/Credit' (Loans/Credit), 'Lotto/Gambling' (Lotto/Gambling), 'Malicious attachment' (Malicious attachment), 'Malicious Software' (Malicious Software), 'Misc/Abstract' (Misc/Abstract), 'Misc/General' (Misc/General), 'Obscured Message' (Obscured Message), 'Phishing Scam' (Phishing Scam), 'Printer Ink' (Printer Ink), 'RX/Fake Cures' (RX/Fake Cures), 'Travel' (Travel), 'Unethical Software' (Unethical Software), 'Pirated Software' (Pirated Software), 'Anti-virus software' (Anti-virus software), 'URL' (URL) |
whitelist_reason | String | Possible values: 'approved sender' (Approved sender), 'not approved sender' (Not approved sender), 'HasWhitelistCode' (System message), 'Custom Filter' (Custom Filter), 'all' (All whitelisted), 'none' (Exclude whitelisted) |
bulk_mail | String | Possible values: 'yes' (Yes), 'no' (No) |
has_attachment | String | Possible values: 'yes' (Yes), 'no' (No) |
was_deep_filtered | String |
Deep filtered Possible values: 'yes' (Yes), 'yes_exclude' (Yes (excluding currently deep filtering)), 'no' (No), 'current' (Currently deep filtering) |
potential_impersonation | String | Possible values: 'yes' (Yes), 'no' (No) |
SPF | String | Possible values: 'unknown' (Unknown), 'none' (None), 'pass' (Pass), 'softfail' (Soft fail), 'fail' (Fail), 'neutral' (Neutral), 'permerror' (Permanent error), 'temperror' (Temporary error), 'extended' (Passed extended SPF) |
DKIM | String | Possible values: 'unknown' (Unknown), 'none' (None), 'pass' (Pass), 'fail' (Fail), 'permerror' (Permanent error), 'temperror' (Temporary error) |
DMARC | String | Possible values: 'unknown' (Unknown), 'none' (None), 'pass' (Pass), 'fail' (Fail), 'permerror' (Permanent error), 'temperror' (Temporary error) |
auth | String |
Authentication scenarios Possible values: 'dmarc_quarantine' (DMARC fail + policy of reject or quarantine), 'not_authenticated' (Fails SPF and DKIM (or has neither)), 'auth_fail' (Fails SPF and DKIM), 'auth_none' (Has neither SPF nor DKIM) |
confirmed_source | String | Confirmed source |
sender_aligned | String | Possible values: 'yes' (Yes), 'no' (No) |
queue_id | String | Queue ID |
sender_ip | String | Sender IP |
size | String | |
key | String | Message key |
rule_id | String | Core engine rule ID |
host_code | String | Filter host that received the message. Check a message header for examples. |
sender_dkim_signer | String | |
delivery_status | String | |
filter_root | String |
Filter category Possible values: 'main_filter' (Main filtering engine), 'AttachmentFilter' (Attachment filter), 'AttachmentFilterExceptions' (Attachment filter exceptions), 'UrlCheck' (Blacklisted URL), 'BlockedSenders' (Blocked sender), 'BulkMailPolicy' (Bulk mail policy), 'CorruptArchivePolicy' (Corrupt archive policy), 'CustomFilterRules' (Custom filter rule), 'CustomFilterRulesExceptions' (Custom filter rule exceptions), 'DmarcPolicy' (DMARC Failure), 'GeographicPolicies' (Geographic Policy), 'GeographicTrashIfSpamPolicies' (Geographic Policy (delete)), 'ApprovedSenders' (Impersonation protection on Approved Sender), 'InvalidSenderDomainPolicy' (Invalid sender domain policy), 'OfficeMacrosPolicy' (MS Office macro attachment policy), 'NonEnglishLanguagePolicy' (Non-English policy), 'MissedSpamFingerprint' (Reported spam), 'SenderAuthAlignedPolicy' (Sender authentication alignment policy), 'SenderAuthFailedPolicy' (Sender authentication failed policy), 'SenderAuthMissingPolicy' (Sender authentication missing policy), 'SexualContentPolicy' (Sexual content policy), 'SuspiciousSenderSource' (Suspicious sender source), 'AllFilteringDisabledForSource' (Unfiltered source), 'UnsafeAttachment' (Unsafe attachment), 'VirusScanClamAV' (Virus) |
filter_context | String |
Filter subcategory Possible values: 'Adult/Porn/Dating' (Adult/Porn/Dating), 'ApprovedSender' (ApprovedSender), 'confirmedSpamSource' (ConfirmedSpamSource), 'domain' (Domain), 'Get-Rich Quick' (Get-Rich Quick), 'Insurance' (Insurance), 'likelySpamSource' (LikelySpamSource), 'Loans/Credit' (Loans/Credit), 'Misc/Abstract' (Misc/Abstract), 'Misc/General' (Misc/General), 'Obscured Message' (Obscured Message), 'Phishing Scam' (Phishing Scam), 'RX/Fake Cures' (RX/Fake Cures), 'SenderVerification' (SenderVerification) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
count | Integer | Number of messages that matched criteria (or total messages, if no criteria was given) |
curl "https://www.spamhero.com/api/email-count?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
GET
Get inbound messages that meet given criteria. This request accepts the same parameters that the quarantine plus page does, so you can check your browser's devtools on the quarantine plus page for what parameters are passed for specific searches
Parameter | Format | Description |
domain* | String | Domain to count messages for (not required if using a domain-specific API key) |
per_page (or 'limit') | Integer (default: 1000) | Maximum number of messages to list at once (max 1,000) |
page | Integer (default: 1) | Desired page number |
recipient | String | Get messages delivered to a specific recipient |
sender | String | Get messages delivered from a specific sender |
start_date | YYYY-MM-DD HH:MM AM/PM | Get messages only after this date. |
end_date | YYYY-MM-DD HH:MM AM/PM | Get messages only before this date. |
offset | Integer |
Offset for getting messages. Can be used in combination with (or instead of) page parameter.
|
status | String (default: all-spam) | Possible values: 'all', 'all-and-deleted', 'all-clean', 'delivered', 'pending', 'delivered-delayed', 'failed', 'pending-failed', 'false-positive', 'whitelist', 'all-spam', 'missed-spam', 'deleted-spam', 'all-spam-deleted' |
sender_name | String | Sender name |
sender_email | String | |
sender_messageid | String | Message ID |
domainid | String | |
sender_host_alignment | String | |
deepfilter_hit | String |
Deep filter reason Possible values: 'UnsafeAttachment-suspicious' (Suspicious attachment), 'DmarcPolicy-fail' (DMARC failure) |
filter_rule_id | String | Filter rule ID |
deepfilter_rule_id | String | Deep filter rule ID |
msg_group | String | Message selection ID |
fingerprint | String | |
mid | String | Message Record ID |
recipient | String | To |
recipient_email | String | |
actual_recipient_email | String | Recipient |
subject | String | |
attachment_list | String | Attachment file name |
country | String |
Sender country Possible values: 'af' (Afghanistan), 'ax' (Aland Islands), 'al' (Albania), 'dz' (Algeria), 'ad' (Andorra), 'ao' (Angola), 'ai' (Anguilla), 'ag' (Antigua and Barbuda), 'ar' (Argentina), 'am' (Armenia), 'aw' (Aruba), 'ap' (Asia/Pacific Region), 'au' (Australia), 'at' (Austria), 'az' (Azerbaijan), 'bs' (Bahamas), 'bh' (Bahrain), 'bd' (Bangladesh), 'bb' (Barbados), 'by' (Belarus), 'be' (Belgium), 'bz' (Belize), 'bj' (Benin), 'bm' (Bermuda), 'bt' (Bhutan), 'bo' (Bolivia), 'bq' (Bonaire, Saint Eustatius and Saba), 'ba' (Bosnia and Herzegovina), 'bw' (Botswana), 'br' (Brazil), 'vg' (British Indian Ocean Territory), 'bn' (Brunei Darussalam), 'bg' (Bulgaria), 'bf' (Burkina Faso), 'bi' (Burundi), 'kh' (Cambodia), 'cm' (Cameroon), 'ca' (Canada), 'cv' (Cape Verde), 'ky' (Cayman Islands), 'cf' (Central African Republic), 'td' (Chad), 'cl' (Chile), 'cn' (China), 'cx' (Christmas Island), 'cc' (Cocos (Keeling) Islands), 'co' (Colombia), 'km' (Comoros), 'cg' (Congo (Brazzaville)), 'cd' (Congo, The Democratic Republic of the), 'ck' (Cook Islands), 'cr' (Costa Rica), 'ci' (Cote D'Ivoire), 'hr' (Croatia), 'cu' (Cuba), 'cw' (Curacao), 'cy' (Cyprus), 'cz' (Czech Republic), 'dk' (Denmark), 'dj' (Djibouti), 'dm' (Dominica), 'do' (Dominican Republic), 'ec' (Ecuador), 'eg' (Egypt), 'sv' (El Salvador), 'gq' (Equatorial Guinea), 'er' (Eritrea), 'ee' (Estonia), 'et' (Ethiopia), 'eu' (Europe (Country unknown)), 'fk' (Falkland Islands (Malvinas)), 'fo' (Faroe Islands), 'fj' (Fiji), 'fi' (Finland), 'fr' (France), 'gf' (French Guiana), 'pf' (French Polynesia), 'tf' (French Southern Territories), 'ga' (Gabon), 'gm' (Gambia), 'ge' (Georgia), 'de' (Germany), 'gh' (Ghana), 'gi' (Gibraltar), 'gr' (Greece), 'gl' (Greenland), 'gd' (Grenada), 'gp' (Guadeloupe), 'gu' (Guam), 'gt' (Guatemala), 'gg' (Guernsey), 'gn' (Guinea), 'gw' (Guinea-Bissau), 'gy' (Guyana), 'ht' (Haiti), 'hn' (Honduras), 'hk' (Hong Kong), 'hu' (Hungary), 'is' (Iceland), 'in' (India), 'id' (Indonesia), 'ir' (Iran), 'iq' (Iraq), 'ie' (Ireland), 'im' (Isle of Man), 'il' (Israel), 'it' (Italy), 'jm' (Jamaica), 'jp' (Japan), 'je' (Jersey), 'jo' (Jordan), 'kz' (Kazakhstan), 'ke' (Kenya), 'ki' (Kiribati), 'kp' (Korea, North), 'kr' (Korea, South), 'kv' (Kosovo), 'kw' (Kuwait), 'kg' (Kyrgyzstan), 'la' (Laos), 'lv' (Latvia), 'lb' (Lebanon), 'ls' (Lesotho), 'lr' (Liberia), 'ly' (Libya), 'li' (Liechtenstein), 'lt' (Lithuania), 'lu' (Luxembourg), 'mo' (Macau), 'mk' (Macedonia), 'mg' (Madagascar), 'mw' (Malawi), 'my' (Malaysia), 'mv' (Maldives), 'ml' (Mali), 'mt' (Malta), 'mh' (Marshall Islands), 'mq' (Martinique), 'mr' (Mauritania), 'mu' (Mauritius), 'yt' (Mayotte), 'mx' (Mexico), 'fm' (Micronesia), 'md' (Moldova), 'mc' (Monaco), 'mn' (Mongolia), 'ms' (Monserrat), 'me' (Montenegro), 'ma' (Morocco), 'mz' (Mozambique), 'mm' (Myanmar), 'na' (Namibia), 'nr' (Nauru), 'np' (Nepal), 'nl' (Netherlands), 'nc' (New Caledonia), 'nz' (New Zealand), 'ni' (Nicaragua), 'ne' (Niger), 'ng' (Nigeria), 'nu' (Niue), 'nf' (Norfolk Island), 'mp' (Northern Mariana Islands), 'no' (Norway), 'om' (Oman), 'pk' (Pakistan), 'pw' (Palau), 'ps' (Palestinian Territories), 'pa' (Panama), 'pg' (Papua New Guinea), 'py' (Paraguay), 'pe' (Peru), 'ph' (Phillipines), 'pn' (Pitcairn Islands), 'pl' (Poland), 'pt' (Portugal), 'pr' (Puerto Rico), 'qa' (Qatar), 're' (Reunion), 'ro' (Romania), 'ru' (Russia), 'rw' (Rwanda), 'sh' (Saint Helena), 'lc' (Saint Lucia), 'mf' (Saint Martin), 'pm' (Saint Pierre and Miquelon), 'vc' (Saint Vincent and the Grenadines), 'bl' (Saint-Barthelemy), 'ws' (Samoa), 'as' (Samoa, American), 'sm' (San Marino), 'sa' (Saudi Arabia), 'sn' (Senegal), 'rs' (Serbia), 'sc' (Seychelles), 'sl' (Sierra Leone), 'sg' (Singapore), 'sx' (Sint Maarten), 'sk' (Slovakia), 'si' (Slovenia), 'sb' (Solomon Islands), 'so' (Somalia), 'za' (South Africa), 'gs' (South Georgia and the South Sandwich Islands), 'ss' (South Sudan), 'es' (Spain), 'lk' (Sri Lanka), 'kn' (St. Kitts and Nevis), 'sd' (Sudan), 'sr' (Suriname), 'sj' (Svalbard and Jan Mayen Islands), 'sz' (Swaziland), 'se' (Sweden), 'ch' (Switzerland), 'sy' (Syria), 'tw' (Taiwan), 'tj' (Tajikistan), 'tz' (Tanzania), 'th' (Thailand), 'tl' (Timor Leste (West)), 'tg' (Togo), 'tk' (Tokelau), 'to' (Tonga), 'tt' (Trinidad and Tobago), 'tn' (Tunisia), 'tr' (Turkey), 'tm' (Turkmenistan), 'tc' (Turks and Caicos Islands), 'tv' (Tuvalu), 'ug' (Uganda), 'ua' (Ukraine), 'ae' (United Arab Emirates), 'gb' (United Kingdom), 'um' (United States Minor Outlying Islands), 'us' (United States), 'XX' (Unknown), 'uy' (Uruguay), 'uz' (Uzbekistan), 'vu' (Vanuatu), 'va' (Vatican City State), 've' (Venezuela), 'vn' (Vietnam), 'vi' (Virgin Islands (US)), 'wf' (Wallis and Futuna), 'eh' (Western Sahara), 'st' (Western Sahara), 'ye' (Yemen), 'zm' (Zambia), 'zw' (Zimbabwe) |
date | String | YYYY-MM-DD |
header_date | String | |
reason | String | Spam category |
master | String | Search Searches 'sender' or 'recipient' or 'subject' or 'envelope_sender' or 'recipient_email' or 'filter_rule_id' or 'deepfilter_rule_id' |
spf_result | String | |
envelope_sender | String | Return-Path |
sender | String | From |
filter_details | String |
Spam category Possible values: 'Filtering disabled' (Filtering disabled), 'policy_geo' (Geographic Policy), 'Custom Filter' (Custom Filter), 'blocked sender' (Blocked sender), 'policy:foreignchars' (Non-English character set), 'policy:badheaders' (Invalid headers), 'clamav' (Virus), 'policy:UnsafeAttachment' (Unsafe attachment), 'policy:CorruptArchive' (Corrupt and password protected archives), 'url blacklist' (URL blacklist), 'htma3' (HTML Redirect Attachment), 'htma4' (HTML Javascript Attachment), 'policy:missedspam_autoblocksender' (Confirmed sender from missed spam report), 'policy:SPF' (SPF sender authentication), 'Sender alignment mismatch' (Sender alignment mismatch), 'Edge Rule' (Edge Rule), 'Possible Spam Source' (Possible Spam Source), 'Confirmed Spam Source' (Confirmed Spam Source), 'Adult/Porn/Dating' (Dating/Adult/Porn), 'DeepRush' (DeepRush), 'Get-Rich Quick' (Get-Rich Quick), 'Insurance' (Insurance), 'Likely Spam Source' (Likely Spam Source), 'Loans/Credit' (Loans/Credit), 'Lotto/Gambling' (Lotto/Gambling), 'Malicious attachment' (Malicious attachment), 'Malicious Software' (Malicious Software), 'Misc/Abstract' (Misc/Abstract), 'Misc/General' (Misc/General), 'Obscured Message' (Obscured Message), 'Phishing Scam' (Phishing Scam), 'Printer Ink' (Printer Ink), 'RX/Fake Cures' (RX/Fake Cures), 'Travel' (Travel), 'Unethical Software' (Unethical Software), 'Pirated Software' (Pirated Software), 'Anti-virus software' (Anti-virus software), 'URL' (URL) |
whitelist_reason | String | Possible values: 'approved sender' (Approved sender), 'not approved sender' (Not approved sender), 'HasWhitelistCode' (System message), 'Custom Filter' (Custom Filter), 'all' (All whitelisted), 'none' (Exclude whitelisted) |
bulk_mail | String | Possible values: 'yes' (Yes), 'no' (No) |
has_attachment | String | Possible values: 'yes' (Yes), 'no' (No) |
was_deep_filtered | String |
Deep filtered Possible values: 'yes' (Yes), 'yes_exclude' (Yes (excluding currently deep filtering)), 'no' (No), 'current' (Currently deep filtering) |
potential_impersonation | String | Possible values: 'yes' (Yes), 'no' (No) |
SPF | String | Possible values: 'unknown' (Unknown), 'none' (None), 'pass' (Pass), 'softfail' (Soft fail), 'fail' (Fail), 'neutral' (Neutral), 'permerror' (Permanent error), 'temperror' (Temporary error), 'extended' (Passed extended SPF) |
DKIM | String | Possible values: 'unknown' (Unknown), 'none' (None), 'pass' (Pass), 'fail' (Fail), 'permerror' (Permanent error), 'temperror' (Temporary error) |
DMARC | String | Possible values: 'unknown' (Unknown), 'none' (None), 'pass' (Pass), 'fail' (Fail), 'permerror' (Permanent error), 'temperror' (Temporary error) |
auth | String |
Authentication scenarios Possible values: 'dmarc_quarantine' (DMARC fail + policy of reject or quarantine), 'not_authenticated' (Fails SPF and DKIM (or has neither)), 'auth_fail' (Fails SPF and DKIM), 'auth_none' (Has neither SPF nor DKIM) |
confirmed_source | String | Confirmed source |
sender_aligned | String | Possible values: 'yes' (Yes), 'no' (No) |
queue_id | String | Queue ID |
sender_ip | String | Sender IP |
size | String | |
key | String | Message key |
rule_id | String | Core engine rule ID |
host_code | String | Filter host that received the message. Check a message header for examples. |
sender_dkim_signer | String | |
delivery_status | String | |
filter_root | String |
Filter category Possible values: 'main_filter' (Main filtering engine), 'AttachmentFilter' (Attachment filter), 'AttachmentFilterExceptions' (Attachment filter exceptions), 'UrlCheck' (Blacklisted URL), 'BlockedSenders' (Blocked sender), 'BulkMailPolicy' (Bulk mail policy), 'CorruptArchivePolicy' (Corrupt archive policy), 'CustomFilterRules' (Custom filter rule), 'CustomFilterRulesExceptions' (Custom filter rule exceptions), 'DmarcPolicy' (DMARC Failure), 'GeographicPolicies' (Geographic Policy), 'GeographicTrashIfSpamPolicies' (Geographic Policy (delete)), 'ApprovedSenders' (Impersonation protection on Approved Sender), 'InvalidSenderDomainPolicy' (Invalid sender domain policy), 'OfficeMacrosPolicy' (MS Office macro attachment policy), 'NonEnglishLanguagePolicy' (Non-English policy), 'MissedSpamFingerprint' (Reported spam), 'SenderAuthAlignedPolicy' (Sender authentication alignment policy), 'SenderAuthFailedPolicy' (Sender authentication failed policy), 'SenderAuthMissingPolicy' (Sender authentication missing policy), 'SexualContentPolicy' (Sexual content policy), 'SuspiciousSenderSource' (Suspicious sender source), 'AllFilteringDisabledForSource' (Unfiltered source), 'UnsafeAttachment' (Unsafe attachment), 'VirusScanClamAV' (Virus) |
filter_context | String |
Filter subcategory Possible values: 'Adult/Porn/Dating' (Adult/Porn/Dating), 'ApprovedSender' (ApprovedSender), 'confirmedSpamSource' (ConfirmedSpamSource), 'domain' (Domain), 'Get-Rich Quick' (Get-Rich Quick), 'Insurance' (Insurance), 'likelySpamSource' (LikelySpamSource), 'Loans/Credit' (Loans/Credit), 'Misc/Abstract' (Misc/Abstract), 'Misc/General' (Misc/General), 'Obscured Message' (Obscured Message), 'Phishing Scam' (Phishing Scam), 'RX/Fake Cures' (RX/Fake Cures), 'SenderVerification' (SenderVerification) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
messages | Array | Messages that match given criteria |
total | Integer | Total count of messages that match given criteria |
pagination | String | Human readable pagination details |
total_pages | Integer | Total number of pages |
links | Array | An array containing links to the first page, last page, next page, and previous page of records ("next" and "previous" will only appear in the array when they are applicable). These URLs are also available in the return headers. |
curl "https://www.spamhero.com/api/quarantine?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
POST
Release a message by ID (found using the /quarantine endpoint)
Parameter | Format | Description |
domain* | String | Domain to count messages for (not required if using a domain-specific API key) |
id* | Integer | ID of the message to be released (found using the /quarantine endpoint) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | Message stating that the message was released successfully |
curl "https://www.spamhero.com/api/quarantine/release" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE \
-d id=SOME_VALUE
POST
Flush the mail queue
Parameter | Format | Description |
domain* | String | Domain to flush the mail queue for (not required if using a domain-specific API key) |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
message | String | A message confirming that the mail queue has been flushed |
curl "https://www.spamhero.com/api/flush-mail-queue" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE
POST
Create a one-time auto-login link. Note: single-domain API keys cannot generate auto login links, use an account or sub-account API key.
Parameter | Format | Description |
domain* | String | Domain to create auto-login link for |
redirect | String (default: /cp) | Relative page URL to redirect to after logging in. |
control_panel | String | (resellers / enterprise accounts only) Set to 'spamhero' to generate an auto-login URL for the SpamHero control panel instead of your white label control panel |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
url | String | one-time auto-login URL |
curl "https://www.spamhero.com/api/auto-login" \
-u YOUR_API_KEY_HERE: \
-d domain=SOME_VALUE
GET
Check if an auto-login link can be created
Parameter | Format | Description |
domain* | String | Domain to create auto-login link for |
control_panel | String | (resellers / enterprise accounts only) Set to 'spamhero' to check for the domain's sub-account instead of your main account |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
ready | String | Boolean indicating if the API is ready to create an auto-login link |
message* | String | If ready is false, this will contain the reason. |
curl "https://www.spamhero.com/api/auto-login-check?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:
GET
Show which login will be used for third party logins
Parameter | Format | Description |
domain* | String | Domain to create auto-login link for |
control_panel | String | (resellers / enterprise accounts only) Set to 'spamhero' to check for the domain's sub-account instead of your main account |
Property | Format | Description |
success | Boolean |
true if the API request was successful, false if otherwise.
|
login_email | String | email address that will be used for third party logins |
curl "https://www.spamhero.com/api/auto-login-get?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE: