Back to Top

SpamHero API documentation

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.

Table of contents


#

Authenticating

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.


#

API limitations

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.


#

Ordering service for new domains via the API

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.


Getting started

#

/api

Request type: GET / POST

A basic request that does nothing, so you can test authorizing via the API.

Input

(No input accepted)

Output

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:

Ordering & managing domains

#

/api/order

Request type: POST

Order spam filtering services for an additional domain (non-reseller account)

Input

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
*required

Output

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

#

/api/reseller/order

Request type: POST

Order spam filtering services for an additional domain (reseller account)

Input

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)
*required

Output

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

#

/api/cancel-service

Request type: POST

Cancel spam filtering services for a domain.

Input

Parameter Format Description
domain* String Domain to cancel services for.
confirm_domain_to_cancel* String Domain to cancel services for (repeated for confirmation purposes).
*required

Output

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

#

/api/order-check

Request type: GET

Check the status of an order

Input

Parameter Format Description
order_code* String Order code to check on. Provided when the domain was originally ordered via the API.
*required

Output

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:

#

/api/get-required-mx

Request type: GET

Confirm that the MX records for your domain are ready for use, and return the required MX records

Input

Parameter Format Description
domain* String Domain to get required MX records for (not required if using a domain-specific API key)
*required

Output

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.
*This value is not always present
curl "https://www.spamhero.com/api/get-required-mx?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:

#

/api/domains

Request type: GET

Get a list of all domains on your account

Input

Parameter Format Description
include_aliases (or 'alias') String (default: no) "yes" if you want to also get a list of domain aliases

Output

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]])
*This value is not always present
curl "https://www.spamhero.com/api/domains" \
-u YOUR_API_KEY_HERE:

#

/api/mx-check

Request type: GET

Check the MX records for a domain

Input

Parameter Format Description
domain* String Domain to check MX records for (not required if using a domain-specific API key)
*required

Output

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:

#

/api/suspend-service

Request type: POST

Suspend service for a sub-account or domain (API for resellers only)

Input

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)

Output

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

#

/api/reactivate-service

Request type: POST

Reactivate service for a sub-account or domain (API for resellers only)

Input

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)

Output

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

Subscriptions & billing

#

/api/subscriptions/list

Request type: GET

List current subscriptions, with their child subscriptions, current status, and billing information.

Input

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.

Output

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:

#

/api/billing/invoices

Request type: GET

List invoices for your account. Also shows your account's current balance

Input

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.

Output

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:

#

/api/billing/payments

Request type: GET

List recent payments to your account.

Input

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.

Output

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:

#

/api/sub-account/set-custom

Request type: POST

Set the custom value for a given sub-account (For resellers only)

Input

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)
*required

Output

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

Domain aliases

#

/api/alias/add

Request type: POST

Create a domain alias

Input

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
*required

Output

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

#

/api/alias/delete

Request type: POST

Delete a domain alias

Input

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
*required

Output

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

#

/api/alias/mx-check

Request type: GET

Check the MX records for a domain alias

Input

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
*required

Output

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:

Email recipients

#

/api/email-recipient/list

Request type: GET

Get a list of all approved email recipients for a domain (up to 1,000 at a time)

Input

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.
*required

Output

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:

#

/api/email-recipient/add

Request type: POST

Add one or more email recipients to a domain

Input

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
*required

Output

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

#

/api/email-recipient/invalid

Request type: POST

Mark email recipients as invalid (mail for these recipients will be rejected even if your catch-all is enabled)

Input

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
*required

Output

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

#

/api/email-recipient/delete

Request type: POST

Delete email recipients (mail for these recipients will be rejected unless your catch-all is enabled)

Input

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
*required

Output

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

Quarantine users

#

/api/quarantine-user/list

Request type: GET

List existing quarantine users

Input

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.
*required

Output

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:

#

/api/quarantine-user/add

Request type: POST

Add a quarantine user

Input

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.
*required

Output

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

#

/api/quarantine-user/edit

Request type: POST

Edit an existing quarantine user

Input

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.
*required

Output

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

#

/api/quarantine-user/delete

Request type: POST

Delete a quarantine user

Input

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
*required

Output

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

Account contacts

#

/api/account-contact/list

Request type: GET

List existing account contacts

Input

Parameter Format Description
search String Return only account contacts with an email address that matches a search (fully or partially)

Output

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:

#

/api/account-contact/reseller/list

Request type: GET

List existing account contacts an account belonging to your client

Input

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)
*required

Output

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:

#

/api/account-contact/reseller/add

Request type: POST

Add an account contact to one of your client's accounts

Input

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?
*required

Output

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

#

/api/account-contact/reseller/edit

Request type: POST

Edit an account contact belonging to one of your client's accounts

Input

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.
*required

Output

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

#

/api/account-contact/reseller/delete

Request type: POST

Delete an account contact from one of your client's accounts.

Input

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.
*required

Output

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

Manage approved and blocked senders

#

/api/sender/approved/add

Request type: POST

Add one or more approved senders

Input

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
require_verification ['yes', 'no'] (default: yes) `yes` or `no`. If set to `yes`, this approved sender will only apply when the sender's email passes verification.
on_verification_fails ['filter', 'quarantine'] (default: filter) `filter` or `quarantine`. If set to `filter`, emails that claim to be from this sender but fail verification will be filtered as if the sender was not approved. If set to `quarantine`, emails that claim to be from this sender but fail verification will be quarantined. Only applicable if require_verification is set to `yes` (which is the default value).
virus_protection ['enabled', 'disabled'] (default: enabled) `enabled` or `disabled`. If set to `enabled`, emails that contain viruses will continue to be blocked from this sender.
*required

Output

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

#

/api/sender/approved/list

Request type: GET

List existing approved senders

Input

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.
*required

Output

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:

#

/api/sender/approved/delete

Request type: POST

Delete an approved sender

Input

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)
*required

Output

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

#

/api/sender/blocked/add

Request type: POST

Add one or more blocked senders

Input

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
*required

Output

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

#

/api/sender/blocked/list

Request type: GET

List existing blocked senders

Input

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.
*required

Output

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:

#

/api/sender/blocked/delete

Request type: POST

Delete a blocked sender

Input

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)
*required

Output

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

Quarantine & email statistics

#

/api/email-stats

Request type: GET

Count messages received for a domain over a given date range.

Input

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.
*required

Output

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:

#

/api/email-count

Request type: 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.

Input

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), '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)
*required

Output

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:

#

/api/quarantine

Request type: 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

Input

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), '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)
*required

Output

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:

#

/api/quarantine/release

Request type: POST

Release a message by ID (found using the /quarantine endpoint)

Input

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)
*required

Output

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

Tools

#

/api/flush-mail-queue

Request type: POST

Flush the mail queue

Input

Parameter Format Description
domain* String Domain to flush the mail queue for (not required if using a domain-specific API key)
*required

Output

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

Integration

#

/api/auto-login

Request type: 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.

Input

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
*required

Output

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

#

/api/auto-login-check

Request type: GET

Check if an auto-login link can be created

Input

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
*required

Output

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.
*This value is not always present
curl "https://www.spamhero.com/api/auto-login-check?domain=SOME_VALUE" \
-u YOUR_API_KEY_HERE:

#

/api/auto-login-get

Request type: GET

Show which login will be used for third party logins

Input

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
*required

Output

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: