API Documentation

In this guide

Submission Portal REST API
Authorization
Threats Types
Send IP submission
Send Domain submission
Send URL submission
Send RAW email submission
Get submissions counter
Get submissions list

Jump to

Submission Portal REST API

You can access Submission Portal API through a convenient HTTP REST interface, enabling you to report malicious IP addresses, domains, URLs, or emails with suspicious content.

Authorization

To access the API, every request requires a proper Authorization header containing a specific token. Therefore, to get submission access, you must pass a valid token.

To get a token go to https://auth.spamhaus.org/account, scroll down to "API Key Creation" and click "Create Key". Copy the key created. This key will be displayed for one time only.

As an example, the following snippet shows how to retrieve the list of your submissions using the authentication token:

curl -s -H 'Authorization: Bearer AUTH_TOKEN' 
    https://submit.spamhaus.org/portal/api/v1/submissions/list

Authorization: Bearer is the authentication header in the form Authorization: Bearer AUTH_TOKEN

Please note that you should remove the < and > symbols. They are used in this example to contain the token placeholder. The full “AUTH_TOKEN” string should be replaced with the real token.

In case of invalid credentials, you will receive the HTTP 401 error and the following response:

{
  "status": 401,
  "message": "user is not authorized"
}

The authorization scheme is consistent across all the API methods.

Threats Types

When making a submission, it's necessary to specify the detected threat type. This API call allows you to retrieve the list of threats that can be submitted.

URL

GET lookup/threats-types

curl -s -H 'Authorization: Bearer AUTH_TOKEN' 
    https://submit.spamhaus.org/portal/api/v1/lookup/threats-types

Output

[
  {
    "code": "bulletproof-hosting",
    "desc": "bulletproof hosting",
    "type": "*"
  },
  {
    "code": "hijacked-network",
    "desc": "hijacked network",
    "type": "ip"
  },
  ...
]

code threat type code key. It's the string to be passed to the APIs when sending a submission.
desc threat type description
type identifies the key type. It can be an asterisk, which indicates that you can use it for any type of submission (ip, email, domain, url), or it can indicate the type of submission for which you can use it.

Send IP submission

When you suspect an IP address is malicious, you can use this API call to report it to us.

Endpoint URL

POST submissions/add/ip

curl -s -H 'Content-Type: application/json' -H 'Authorization: Bearer AUTH_TOKEN' --data-raw '{
    "threat_type": "source-of-spam",
    "reason": "found on a forum",
    "source": {
        "object":"221.22.34.2"
    }
}' https://submit.spamhaus.org/portal/api/v1/submissions/add/ip

threat_type threat type code key. Codes keys can be fetched using Threats Types API above
reason reason for submission (max length: 255 characters)
source.object source IP submission

Output

Success

{
  "threat_type": "source-of-spam",
  "reason": "hitting personal mailbox without COI",
  "id": "b0f67e0bae18ee10240905843bbb22c21af35c722f2d96f97f2863d63388e784",
  "submission_type": "ip",
  "source": {
    "object": "221.22.34.3"
  }
}

Submission already reported

{
    "status":208,
    "message":"submission already reported"
}

Bad request

{
    "status":400,
    "message":"invalid IP address provided"
}

Return Codes

200 Submission successfully
208 Submission already reported
400 Bad request (ip missing or invalid, threat_type invalid, etc)

Send Domain submission

When you suspect a domain is malicious, you can use this API call to report it to us.

Endpoint URL

POST submissions/add/domain

curl -s -H 'Content-Type: application/json' -H 'Authorization: Bearer AUTH_TOKEN' --data-raw '{
    "threat_type": "source-of-spam",
    "reason": "this domain is very bad",
    "source": {
        "object":"www.baddomain.com"
    }
}' https://submit.spamhaus.org/portal/api/v1/submissions/add/domain

threat_type threat type code key. Codes keys can be fetched using Threats Types API above
reason reason for submission (max length: 255 characters)
source.address source domain submission

Output

Success

{
    "threat_type": "source-of-spam",
    "reason": "this domain is very bad",
    "id": "ae6719a510a3ee3afd0a535138c2be0e3ec17cc22a490806b62940a629f40056",
    "submission_type": "domain",
    "source": {
        "object": "www.baddomain.com"
    }
}

Submission already reported

{
    "status":208,
    "message":"submission already reported"
}

Bad request

{
    "status":400,
    "message":"invalid domain address provided"
}

Return Codes

200 Submission successfully
208 Submission already reported
400 Bad request (domain missing or invalid, threat_type invalid, etc)

Send URL submission

When you suspect an URL is malicious, you can use this API call to report it to us.

Endpoint URL

POST submissions/add/url

curl -s -H 'Content-Type: application/json' -H 'Authorization: Bearer AUTH_TOKEN' --data-raw '{
    "threat_type": "source-of-spam",
    "reason": "this url sends spam",
    "source": {
        "object":"baddomain.com/get/files/ddd"
    }
}' https://submit.spamhaus.org/portal/api/v1/submissions/add/url

threat_type threat type code key. Codes keys can be fetched using Threats Types API above
reason reason for submission (max length: 255 characters)
source.object source URL submission

Output

Success

{
    "threat_type": "source-of-spam",
    "reason": "this url sends spam",
    "id": "3ed4bd41c8d7c57a38cbc2576a99273e7a6087ab4ad148b545206b39ca3d0c04",
    "submission_type": "url",
    "source": {
        "object": "baddomain.com/get/files/ddd"
    }
}

Submission already reported

{
    "status":208,
    "message":"submission already reported"
}

Bad request

{
    "status":400,
    "message":"invalid URL address provided"
}

Return Codes

200 Submission successfully
208 Submission already reported
400 Bad request (URL missing or invalid, threat_type invalid, etc)

Send RAW email submission

When you suspect an email contains malicious content, you can use this API call to report it to us.

You can find step-by-step guidance on sending RAW email source code using BASH or PHP scripts here.

Endpoint URL

POST submissions/add/email

curl -s -H 'Content-Type: application/json' -H 'Authorization: Bearer AUTH_TOKEN' --data-raw '{
    "threat_type": "source-of-spam",
    "reason": "this email contains a virus",
    "source": {
        "object":<RAW EMAIL CONTENT>
    }
}' https://submit.spamhaus.org/portal/api/v1/submissions/add/email

threat_type threat type code key. Codes keys can be fetched using Threats Types API above
reason reason for submission (max length: 255 characters)
source.object source RAW email content. It's the malevolant email RAW content (max raw content length: 150Kb)

RAW email content sample

Received: from mail.example.com (mail.example.com [192.168.1.1])
    by mailserver.example.net (Postfix) with ESMTP id ABC12345
    for <recipient@example.net>; Thu, 6 Sep 2023 09:00:00 -0400 (EDT)
Date: Thu, 6 Sep 2023 09:00:00 -0400 (EDT)
From: sender@example.com
To: recipient@example.net
Subject: Oggetto dell'email
Message-ID: <1234567890@example.com>
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"

This is the email body. Hello.

Output

Success

{
    "threat_type": "source-of-spam",
    "reason": "deo",
    "id": "83ce6737149a9fec5d793892816d3eafca55217fef9329555bad9829e3e818d0",
    "submission_type": "email",
    "source": {
        "object":<RAW EMAIL CONTENT>
    }
}

Submission already reported

{
    "status":208,
    "message":"submission already reported"
}

Bad request

{
    "status":400,
    "message":"unable to parse email content"
}

Return Codes

200 Submission successfully
208 Submission already reported
400 Bad request (email content missing or invalid, threat_type invalid, etc)

Get submissions counter

Use this API call to retrieve the total number of submissions you have sent and the number of submissions whose content has been found in one or more dataset.

This is limited to submissions sent in the last 30 days.

Endpoint URL

GET submissions/count

Output

{
    "total": 7,
    "matched": 3
}

total total number of submissions sent
matched total number of submissions found in one or more dataset

Get submissions list

Use this API call to retrieve your submissions list, among with their validation status.

This is limited to submissions sent in the last 30 days.

Endpoint URL

GET submissions/list

This request can be paginated.

items - items per page (default 100, max 10000)
page - page number (default 1)

Output

[
    {
        "threat_type": "source-of-spam",
        "reason": "found on a forum",
        "id": "b0c8d9da509644e8dba62f36e24f19022071d17214830e6a0aebed84a9554bd8",
        "submission_type": "ip",
        "source": {
            "object": "221.22.34.2"
        },
        "attributes": {
            "address": "221.22.34.2",
            "mask": "32"
        },
        "listed": null,
        "last_check": null,
        "submission_ts": "2023-09-06T09:38:40.408161Z"
    }
]

Output array is empty if there are no submissions or you can find one or more submissions in the format described below

When your submission is reviewed by our team and has not been found in any dataset, the listed field is null and last_check contains the timestamp of the last check performed.

If the submission has been found in one or more datasets, the listed field will contain an array listing the datasets in which it was found.

[
    {
        "threat_type": "source-of-spam",
        "reason": "found on a forum",
        "id": "b0c8d9da509644e8dba62f36e24f19022071d17214830e6a0aebed84a9554bd8",
        "submission_type": "ip",
        "source": {
            "object": "221.22.34.2"
        },
        "attributes": {
            "address": "221.22.34.2",
            "mask": "32"
        },
        "listed": ["XBL", "SBL"],
        "last_check": "2023-09-06T09:38:40.408161Z",
        "submission_ts": "2023-09-06T09:38:40.408161Z"
    }
]

Email submission

{
    "threat_type": "source-of-spam",
    "reason": "malevolant email content",
    "id": "83ce6737149a9fec5d793892816d3eafca55217fef9329555bad9829e3e818d0",
    "submission_type": "email",
    "source": {
        "object": <raw email content>
    },
    "attributes": {
        "subject": "Buy stuff"
    },
    "listed": null,
    "last_check": null,
    "submission_ts": "2023-09-06T12:39:40.162738Z"
}

threat_type threat type code key. Codes keys can be fetched using Threats Types API above
reason reason for submission
source.object your submission payload original content (raw email string)
id submission identification number
submission_type submission type provided (email for emails submissions)
attributes information extracted from your submission payload (subject email subject)
listed contains the datasets in which the submission has been detected, in the form of strings array. It's null when the submission is new or has not yet been found in any dataset.
last_check last time we checked if the submission was detected in one or more datasets. It's null when the submission is new or has not yet been found in any dataset.
submission_ts submission receival timestamp

URL submission

{
        "threat_type": "source-of-spam",
        "reason": "this url is bad",
        "id": "3ed4bd41c8d7c57a38cbc2576a99273e7a6087ab4ad148b545206b39ca3d0c04",
        "submission_type": "url",
        "source": {
            "object": "baddomain.com/test"
        },
        "attributes": {
            "sha-256": "b2fb538cd53b88f9f566616993a3d35e6d89088c1dcb7fee25d8a1fc392f2013"
        },
        "listed": null,
        "last_check": null,
        "submission_ts": "2023-09-06T12:34:14.217019Z"
}

threat_type threat type code key. Codes keys can be fetched using Threats Types API above
reason reason for submission
source.object your submission payload original content (raw email string)
id submission identification number
submission_type submission type provided (url for URLs submissions)
attributes information extracted from your submission payload (sha-256 hash string to identify URL string)
listed contains the datasets in which the submission has been detected, in the form of strings array. It's null when the submission is new or has not yet been found in any dataset.
last_check last time we checked if the submission was detected in one or more datasets. It's null when the submission is new or has not yet been found in any dataset.
submission_ts submission receival timestamp

IP submission

{
        "threat_type": "source-of-spam",
        "reason": "found on a forum",
        "id": "b0c8d9da509644e8dba62f36e24f19022071d17214830e6a0aebed84a9554bd8",
        "submission_type": "ip",
        "source": {
            "object": "221.22.34.2"
        },
        "attributes": {
            "address": "221.22.34.2",
            "mask": "32"
        },
        "listed": null,
        "last_check": null,
        "submission_ts": "2023-09-06T09:38:40.408161Z"
}

threat_type threat type code key. Codes keys can be fetched using Threats Types API above
reason reason for submission
source.object your submission payload original content (malevolant IP address)
id submission identification number
submission_type submission type provided (ip for IPs submissions)
attributes information extracted from your submission payload (address IPv4/IPv6 address, mask ip subnet)
listed contains the datasets in which the submission has been detected, in the form of strings array. It's null when the submission is new or has not yet been found in any dataset.
last_check last time we checked if the submission was detected in one or more datasets. It's null when the submission is new or has not yet been found in any dataset.
submission_ts submission receival timestamp

Domain submission

{
        "threat_type": "bulletproof-hosting",
        "reason": "this is a bad domain",
        "id": "449bf8416c18d19a30db6d853f416a2192065c3f44a354f041d9224fc926bde4",
        "submission_type": "domain",
        "source": {
            "object": "www.test.com"
        },
        "attributes": {
            "domain": "test.com",
            "tld": "com"
        },
        "listed": null,
        "last_check": null,
        "submission_ts": "2023-09-04T14:59:17.765406Z"
    }

threat_type threat type code key. Codes keys can be fetched using Threats Types API above
reason reason for submission
source.address your submission payload original content (malevolant domain)
id submission identification number
submission_type submission type provided (domain for domains submissions)
attributes information extracted from your submission payload (domain the domain name, tld the tld of the domain)
listed contains the datasets in which the submission has been detected, in the form of strings array. It's null when the submission is new or has not yet been found in any dataset.
last_check last time we checked if the submission was detected in one or more datasets. It's null when the submission is new or has not yet been found in any dataset.
submission_ts submission receival timestamp