> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/docs/products/email-blacklist

# Email Blacklist API

Check if a domain or IP is listed on email blacklists. Use this reference to pick the right endpoint and see exactly what it returns.

[View product page](https://domscan.net/email-blacklist-api)

## Operations

GET `/v1/email/check` [View API reference](https://domscan.net/docs/products/email-blacklist#checkEmailBlacklist)

POST `/v1/email/check/bulk` [View API reference](https://domscan.net/docs/products/email-blacklist#bulkEmailCheck)

GET `/v1/email/blacklist` [View API reference](https://domscan.net/docs/products/email-blacklist#getEmailBlacklistInfo)

GET `/v1/email/blacklist/download` [View API reference](https://domscan.net/docs/products/email-blacklist#downloadEmailBlacklist)

## GET `/v1/email/check`

Operation: `checkEmailBlacklist`
Credits and authentication: 1
Authentication required

GET /v1/email/check Credits: 1

#### Query parameters

| Parameter | Type | required |
| --- | --- | --- |
| email | string | required |
| checks | string | optional |

#### Response fields

| Field | Type |
| --- | --- |
| `email` | string |
| `domain` | string |
| `local_part` | string |
| `valid_syntax` | boolean |
| `checks` | object |
| `checks.disposable` | object |
| `checks.disposable.is_disposable` | boolean |
| `checks.disposable.confidence` | string \| null |
| `checks.disposable.matched_pattern` | string |
| `checks.role` | object |
| `checks.role.is_role` | boolean |
| `checks.role.role_type` | string \| null |
| `checks.free` | object |
| `checks.free.is_free` | boolean |
| `checks.free.provider` | string \| null |
| `checks.mx` | object |
| `checks.mx.has_mx` | boolean \| null |
| `checks.mx.records[]` | string[] |
| `checks.mx.null_mx` | boolean |
| `checks.dnsbl` | object |
| `checks.dnsbl.domain` | string |
| `checks.dnsbl.ip` | string |
| `checks.dnsbl.listed` | boolean |
| `checks.dnsbl.lists[]` | object[] |
| `checks.dnsbl.lists[]` | object |
| `checks.dnsbl.lists[].name` | string |
| `checks.dnsbl.lists[].listed` | boolean |
| `checks.dnsbl.lists[].status` | string |
| `checks.dnsbl.lists[].code` | string |
| `checks.dnsbl.lists[].meaning` | string |
| `checks.dnsbl.lists[].unknown_reason` | string |
| `checks.dnsbl.lists_unknown` | integer |
| `checks.dnsbl.threat_level` | string |
| `checks.dnsbl.check_type` | string |
| `checks.dnsbl.checked_at` | string |
| `risk_score` | integer |
| `risk_level` | string |
| `flags[]` | string[] |
| `checked_at` | string |

#### Example request

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/email/check?email=user%40example.com&checks=disposable%2Crole%2Cfree%2Cmx%2Cdnsbl"
```

```javascript
const response = await fetch("https://domscan.net/v1/email/check?email=user%40example.com&checks=disposable%2Crole%2Cfree%2Cmx%2Cdnsbl", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/email/check?email=user%40example.com&checks=disposable%2Crole%2Cfree%2Cmx%2Cdnsbl",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/email/check?email=user%40example.com&checks=disposable%2Crole%2Cfree%2Cmx%2Cdnsbl", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/email/check?email=user%40example.com&checks=disposable%2Crole%2Cfree%2Cmx%2Cdnsbl")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### Example response

```json
{
  "email": "support@acme-widgets.com",
  "domain": "acme-widgets.com",
  "local_part": "support",
  "valid_syntax": true,
  "checks": {
    "disposable": {
      "is_disposable": false,
      "confidence": null
    },
    "role": {
      "is_role": true,
      "role_type": "support"
    },
    "free": {
      "is_free": false,
      "provider": null
    },
    "mx": {
      "has_mx": true,
      "records": [
        "mx1.mailhost-example.net",
        "mx2.mailhost-example.net"
      ]
    },
    "dnsbl": {
      "listed": false,
      "threat_level": "none"
    }
  },
  "risk_score": 20,
  "risk_level": "low",
  "flags": [
    "ROLE_ADDRESS"
  ],
  "checked_at": "2026-10-09T10:15:30.000Z"
}
```

#### HTTP status codes

- `200` OK
- `400` Bad Request
- `401` Unauthorized
- `402` Payment Required
- `429` Too Many Requests

## POST `/v1/email/check/bulk`

Operation: `bulkEmailCheck`
Credits and authentication: 1
Authentication required

POST /v1/email/check/bulk Credits: 1/item

#### Query parameters

| Parameter | Type | required |
| --- | --- | --- |
| dry_run | string Allowed values `true` | optional |

#### Body parameters

| Parameter | Type | required |
| --- | --- | --- |
| emails | string[] | required |
| checks | string[] Allowed values `disposable`, `role`, `free`, `mx`, `dnsbl` | optional |

#### Response fields

| Field | Type |
| --- | --- |
| `results[]` | object[] |
| `results[]` | object |
| `summary` | object |
| `summary.total` | integer |
| `summary.disposable` | integer |
| `summary.role_based` | integer |
| `summary.free_provider` | integer |
| `summary.no_mx` | integer |
| `summary.dnsbl_listed` | integer |
| `summary.high_risk` | integer |
| `summary.medium_risk` | integer |
| `summary.low_risk` | integer |
| `checked_at` | string |

#### Example request

```bash
curl -X POST "https://domscan.net/v1/email/check/bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "emails": [
    "jane.doe@example.com",
    "support@example.org"
  ],
  "checks": [
    "disposable",
    "role",
    "mx"
  ]
}'
```

```javascript
const response = await fetch("https://domscan.net/v1/email/check/bulk", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "emails": [
      "jane.doe@example.com",
      "support@example.org"
    ],
    "checks": [
      "disposable",
      "role",
      "mx"
    ]
  }),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.post(
    "https://domscan.net/v1/email/check/bulk",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "emails": [
            "jane.doe@example.com",
            "support@example.org",
        ],
        "checks": [
            "disposable",
            "role",
            "mx",
        ],
    },
)
print(response.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "emails": [
	    "jane.doe@example.com",
	    "support@example.org"
	  ],
	  "checks": [
	    "disposable",
	    "role",
	    "mx"
	  ]
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/email/check/bulk", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/email/check/bulk")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "emails" => [
    "jane.doe@example.com",
    "support@example.org"
  ],
  "checks" => [
    "disposable",
    "role",
    "mx"
  ]
})

#### Example response

```json
{
  "results": [
    {}
  ],
  "summary": {
    "total": 10,
    "disposable": 3,
    "role_based": 1,
    "free_provider": 2,
    "no_mx": 0,
    "dnsbl_listed": 0,
    "high_risk": 3,
    "medium_risk": 1,
    "low_risk": 6
  },
  "checked_at": "2026-08-27T12:00:00Z"
}
```

#### HTTP status codes

- `200` OK
- `400` Bad Request
- `401` Unauthorized
- `402` Payment Required
- `409` HTTP 409
- `422` HTTP 422
- `429` Too Many Requests

## GET `/v1/email/blacklist`

Operation: `getEmailBlacklistInfo`
Credits and authentication: Free
Authentication required

GET /v1/email/blacklist Credits: 0

#### Query parameters

| Parameter | Type | required |
| --- | --- | --- |
| limit | integer Default `1000` | optional |
| offset | integer Default `0` | optional |
| format | string Allowed values `json`, `txt` Default `json` | optional |
| cursor | string | optional |

#### Response fields

| Field | Type |
| --- | --- |
| `has_more` | boolean |
| `next_cursor` | string \| null |
| `domains[]` | string[] |
| `total` | integer |
| `offset` | integer |
| `limit` | integer |
| `metadata` | object |
| `metadata.last_updated` | string |
| `metadata.total_domains` | integer |
| `metadata.high_confidence_count` | integer |
| `metadata.wildcard_count` | integer |
| `metadata.sources[]` | string[] |
| `metadata.source_count` | integer |
| `metadata.successful_source_count` | integer |
| `metadata.failed_source_count` | integer |
| `metadata.refresh_cadence_hours` | integer |
| `metadata.refresh_status` | string |
| `metadata.next_refresh_due` | string |
| `metadata.dataset_status` | string |
| `metadata.quality_policy_version` | integer \| null |
| `metadata.quarantined_domain_count` | integer |
| `metadata.rejected_domain_count` | integer |

#### Example request

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/email/blacklist?limit=25&offset=0&format=json"
```

```javascript
const response = await fetch("https://domscan.net/v1/email/blacklist?limit=25&offset=0&format=json", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/email/blacklist?limit=25&offset=0&format=json",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/email/blacklist?limit=25&offset=0&format=json", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/email/blacklist?limit=25&offset=0&format=json")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### Example response

```json
{
  "domains": [
    "0-00.usa.cc",
    "0-180.com",
    "0-30-24.com"
  ],
  "total": 91331,
  "offset": 0,
  "limit": 3,
  "metadata": {
    "last_updated": "2026-10-09T03:00:07.499Z",
    "total_domains": 91331,
    "high_confidence_count": 5142,
    "wildcard_count": 0,
    "sources": [
      "disposable-email-domains",
      "fakefilter",
      "mailchecker"
    ],
    "source_count": 8,
    "successful_source_count": 8,
    "failed_source_count": 0,
    "refresh_cadence_hours": 24,
    "refresh_status": "fresh",
    "next_refresh_due": "2026-10-10T03:00:07.499Z",
    "dataset_status": "complete",
    "quality_policy_version": 2,
    "quarantined_domain_count": 0,
    "rejected_domain_count": 0
  }
}
```

#### HTTP status codes

- `200` OK
- `400` Bad Request
- `401` Unauthorized
- `429` Too Many Requests

## GET `/v1/email/blacklist/download`

Operation: `downloadEmailBlacklist`
Credits and authentication: Free
Authentication required

GET /v1/email/blacklist/download Credits: 0

#### Query parameters

| Parameter | Type | required |
| --- | --- | --- |
| format | string Allowed values `json`, `txt` Default `json` | optional |

#### Response fields

| Field | Type |
| --- | --- |
| `domains[]` | string[] |
| `wildcards[]` | string[] |
| `metadata` | object |

#### Example request

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/email/blacklist/download?format=json"
```

```javascript
const response = await fetch("https://domscan.net/v1/email/blacklist/download?format=json", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/email/blacklist/download?format=json",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/email/blacklist/download?format=json", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Status, string(data))
}
```

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/email/blacklist/download?format=json")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.pretty_generate(JSON.parse(response.body))
```

#### Example response

```json
{
  "domains": [
    "example.com",
    "example.org"
  ],
  "wildcards": [
    "example"
  ],
  "metadata": {}
}
```

#### HTTP status codes

- `200` OK
- `401` Unauthorized
- `429` Too Many Requests

## Reference resources

[OpenAPI 3.0](https://domscan.net/v1/openapi.json)
[Postman](https://domscan.net/v1/postman.json)
[MCP](https://domscan.net/mcp-domain-checker)
