Blocklist Monitoring

Monitor your sending domains and IP addresses for blocklist hits with MailerSend's Blocklist Monitoring API. Create and manage monitors, receive notifications, and track blocklist status.

Monitor your sending domains and IP addresses for blocklist hits. Create monitors for individual domains, single IPs, or entire CIDR ranges, configure notification endpoints, and track whether your addresses appear on any blocklists.

List monitors

If you want to retrieve a list of your blocklist monitors, use this GET request:

GET https://api.mailersend.com/v1/blocklist-monitoring

Request parameters

Query parameter	Type	Required	Limitations	Details
`limit`	`integer`	no	Min: `1`, Max: `100`	Default: `25`
`page`	`integer`	no	Min: `1`
`query`	`string`	no	Max: `255` chars	Search by name or address
`sort_by`	`string`	no	`name`, `address`, `created_at`, `updated_at`, `blocklisted`	Default: `created_at`
`order`	`string`	no	`asc`, `desc`	Default: `desc`

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
    "data": [
        {
            "id": "5d3e1c9f8b2a4d71",
            "name": "My Domain",
            "address": "example.com",
            "type": "domain",
            "in_progress": false,
            "notify": true,
            "blocklisted": false,
            "last_checks_count": 82,
            "last_check": "2026-03-28T12:00:00.000000Z",
            "next_check": "2026-03-29T12:00:00.000000Z",
            "has_children": false,
            "forwards": [
                {
                    "id": "a1b2c3d4e5f6",
                    "type": "email",
                    "value": "admin@example.com"
                }
            ],
            "created_at": "2026-01-15T08:00:00.000000Z",
            "updated_at": "2026-03-28T12:00:00.000000Z"
        }
    ]
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Get a monitor

If you want to retrieve information about a specific blocklist monitor, use this GET request:

GET https://api.mailersend.com/v1/blocklist-monitoring/{monitor_id}

Request parameters

URL parameter	Type	Required	Limitations	Details
`monitor_id`	`string`	yes

Responses

Valid — single monitor (domain or IP)

For monitors where has_children is false, the response includes a hits array showing current blocklist hits.

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
    "data": {
        "id": "5d3e1c9f8b2a4d71",
        "name": "My Domain",
        "address": "example.com",
        "type": "domain",
        "in_progress": false,
        "notify": true,
        "blocklisted": true,
        "last_checks_count": 82,
        "last_check": "2026-03-28T12:00:00.000000Z",
        "next_check": "2026-03-29T12:00:00.000000Z",
        "has_children": false,
        "forwards": [
            {
                "id": "a1b2c3d4e5f6",
                "type": "email",
                "value": "admin@example.com"
            }
        ],
        "hits": [
            {
                "blocklist_host": "zen.spamhaus.org",
                "address": "example.com",
                "listed_at": "2026-03-20T08:00:00.000000Z",
                "delisted_at": null,
                "last_checked_at": "2026-03-28T12:00:00.000000Z"
            }
        ],
        "created_at": "2026-01-15T08:00:00.000000Z",
        "updated_at": "2026-03-28T12:00:00.000000Z"
    }
}

Valid — IP range monitor

For monitors where has_children is true (created from a CIDR block), the response includes a children array with all child monitors and their current status. No hits array is returned.

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
    "data": {
        "id": "9ae4f7b1c3d2e501",
        "name": "My IP Range",
        "address": "192.0.2.0",
        "type": "ip",
        "in_progress": false,
        "notify": true,
        "blocklisted": true,
        "last_checks_count": 246,
        "last_check": "2026-03-28T12:00:00.000000Z",
        "next_check": "2026-03-29T12:00:00.000000Z",
        "has_children": true,
        "children_count": 3,
        "forwards": [
            {
                "id": "b2c3d4e5f601",
                "type": "webhook",
                "value": "https://example.com/hook"
            }
        ],
        "children": [
            {
                "id": "c3d4e5f60102",
                "name": "192.0.2.1",
                "address": "192.0.2.1",
                "type": "ip",
                "in_progress": false,
                "notify": false,
                "blocklisted": true,
                "last_checks_count": 82,
                "last_check": "2026-03-28T12:00:00.000000Z",
                "next_check": "2026-03-29T12:00:00.000000Z",
                "has_children": false,
                "forwards": [],
                "created_at": "2026-01-15T08:00:00.000000Z",
                "updated_at": "2026-03-28T12:00:00.000000Z"
            }
        ],
        "created_at": "2026-01-15T08:00:00.000000Z",
        "updated_at": "2026-03-28T12:00:00.000000Z"
    }
}

Error

Response Code: 404 Not Found

Create a monitor

If you want to create a new blocklist monitor, use this POST request:

POST https://api.mailersend.com/v1/blocklist-monitoring

Request parameters

JSON parameters are provided in dot notation

JSON parameter	Type	Required	Limitations	Details
`address`	`string`	yes	Max: `255` chars	Domain name, IP address, or CIDR block (e.g. `192.0.2.0/24`). Domains must be verified sending domains on the account. IPv4 CIDR: `/24`–`/32`. IPv6 CIDR: `/120`–`/128`. Each address can only be monitored once.
`name`	`string`	no	Max: `255` chars	Display name. Defaults to the address value.
`notify`	`boolean`	no		Whether to send notifications when a blocklist hit is detected.
`notify_email`	`string`	no	Valid email. Max: `255`. Required if `notify` is `true` and `notify_address` is absent.	Email address to notify.
`notify_address`	`string`	no	Valid URL. Max: `500`. Required if `notify` is `true` and `notify_email` is absent.	Webhook URL to notify.

Request body

{
    "address": "example.com",
    "name": "My Domain",
    "notify": true,
    "notify_email": "admin@example.com"
}

Responses

Valid

Response Code: 201 CREATED
Response Headers:
	content-type: application/json

{
    "data": {
        "id": "5d3e1c9f8b2a4d71",
        "name": "My Domain",
        "address": "example.com",
        "type": "domain",
        "in_progress": true,
        "notify": true,
        "blocklisted": false,
        "last_checks_count": 0,
        "last_check": null,
        "next_check": null,
        "has_children": false,
        "forwards": [
            {
                "id": "a1b2c3d4e5f6",
                "type": "email",
                "value": "admin@example.com"
            }
        ],
        "created_at": "2026-03-30T10:00:00.000000Z",
        "updated_at": "2026-03-30T10:00:00.000000Z"
    }
}

When creating a monitor for a CIDR block, one parent monitor and one child monitor per IP in the range are created automatically. The in_progress field will be true while the initial check is running.

IP range example request:

{
    "address": "192.0.2.0/30",
    "name": "My IP Range"
}

IP range example response:

{
    "data": {
        "id": "9ae4f7b1c3d2e501",
        "name": "My IP Range",
        "address": "192.0.2.0",
        "type": "ip",
        "in_progress": true,
        "notify": false,
        "blocklisted": false,
        "last_checks_count": 0,
        "last_check": null,
        "next_check": null,
        "has_children": true,
        "children_count": 4,
        "forwards": [],
        "created_at": "2026-03-30T10:00:00.000000Z",
        "updated_at": "2026-03-30T10:00:00.000000Z"
    }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Update a monitor

If you want to update an existing blocklist monitor, use this PUT request:

PUT https://api.mailersend.com/v1/blocklist-monitoring/{monitor_id}

Request parameters

URL parameter	Type	Required	Limitations	Details
`monitor_id`	`string`	yes

JSON parameters are provided in dot notation

JSON parameter	Type	Required	Limitations	Details
`name`	`string`	no	Max: `255` chars	New display name.
`notify`	`boolean`	no		Enable or disable notifications.
`notify_email`	`string`	no	Valid email. Max: `255`. Required if `notify` is `true` and `notify_address` is absent.	Email address to notify.
`notify_address`	`string`	no	Valid URL. Max: `500`. Required if `notify` is `true` and `notify_email` is absent.	Webhook URL to notify.

Request body

{
    "name": "Updated Name",
    "notify": true,
    "notify_email": "alerts@example.com"
}

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

The response has the same shape as the Get a monitor response.

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Delete a monitor

If you want to delete a blocklist monitor, use this DELETE request:

DELETE https://api.mailersend.com/v1/blocklist-monitoring/{monitor_id}

Request parameters

URL parameter	Type	Required	Limitations	Details
`monitor_id`	`string`	yes

If the monitor is a parent (IP range), all child monitors are deleted automatically.

Responses

Valid

Response Code: 204 No Content

Error

Response Code: 404 Not Found

On this page