Account

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`

use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->blocklistMonitoring->getAll($page = 1, $limit = 25);

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.blocklistMonitor.list({ page: 1, limit: 25 })
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.blocklistmonitoring.BlocklistMonitor;
import com.mailersend.sdk.blocklistmonitoring.BlocklistMonitorsList;
import com.mailersend.sdk.exceptions.MailerSendException;

public void listBlocklistMonitors() {

    MailerSend ms = new MailerSend();
    ms.setToken("Your API token");

    try {

        BlocklistMonitorsList list = ms.blocklistMonitoring().page(1).limit(25).getMonitors();

        for (BlocklistMonitor monitor : list.monitors) {
            System.out.println(monitor.id);
            System.out.println(monitor.name);
            System.out.println(monitor.address);
            System.out.println(monitor.type);
            System.out.println(monitor.blocklisted);
        }

    } catch (MailerSendException e) {
        e.printStackTrace();
    }
}

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": 0,
            "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"
        }
    ],
    "links": {
        "first": "https://api.mailersend.com/v1/blocklist-monitoring?page=1",
        "last": null,
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "current_page_url": "https://api.mailersend.com/v1/blocklist-monitoring?page=1",
        "from": 1,
        "path": "https://api.mailersend.com/v1/blocklist-monitoring",
        "per_page": 25,
        "to": 1
    }
}

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

use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->blocklistMonitoring->find('monitor-id');

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.blocklistMonitor.single("monitor_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.blocklistmonitoring.BlocklistMonitor;
import com.mailersend.sdk.exceptions.MailerSendException;

public void getBlocklistMonitor() {

    MailerSend ms = new MailerSend();
    ms.setToken("Your API token");

    try {

        BlocklistMonitor monitor = ms.blocklistMonitoring().getMonitor("your-monitor-id");

        System.out.println(monitor.id);
        System.out.println(monitor.name);
        System.out.println(monitor.address);
        System.out.println(monitor.type);
        System.out.println(monitor.blocklisted);
        System.out.println(monitor.notify);

    } catch (MailerSendException e) {
        e.printStackTrace();
    }
}

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": 1,
        "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": 1,
        "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": "My IP Range",
                "address": "192.0.2.1",
                "type": "ip",
                "in_progress": false,
                "notify": false,
                "blocklisted": 1,
                "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; trial domains cannot be monitored. IPv4 addresses and ranges that include MailerSend shared sending IPs cannot be monitored. 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"
}

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\BlocklistMonitoringParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->blocklistMonitoring->create(
    (new BlocklistMonitoringParams('example.com'))
        ->setName('My Domain')
        ->setNotify(true)
        ->setNotifyEmail('admin@example.com')
);

import 'dotenv/config';
import { MailerSend, BlocklistMonitor } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

const monitor = new BlocklistMonitor("example.com")
  .setName("My Domain")
  .setNotify(true)
  .setNotifyEmail("admin@example.com");

mailerSend.blocklistMonitor.create(monitor)
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.blocklistmonitoring.BlocklistMonitor;
import com.mailersend.sdk.exceptions.MailerSendException;

public void createBlocklistMonitor() {

    MailerSend ms = new MailerSend();
    ms.setToken("Your API token");

    try {

        BlocklistMonitor monitor = ms.blocklistMonitoring().createMonitorBuilder()
                .name("My Domain")
                .notify(true)
                .notifyEmail("admin@example.com")
                .createMonitor("example.com");

        System.out.println(monitor.id);
        System.out.println(monitor.name);
        System.out.println(monitor.address);

    } catch (MailerSendException e) {
        e.printStackTrace();
    }
}

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"
}

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": 0,
        "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"
    }
}

IP range example response:

{
    "data": {
        "id": "9ae4f7b1c3d2e501",
        "name": "My IP Range",
        "address": "192.0.2.0",
        "type": "ip",
        "in_progress": true,
        "notify": false,
        "blocklisted": 0,
        "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: 403 Forbidden
Response Headers:
	content-type: application/json

{
    "message": "The number of monitors to create exceeds your current plan limit."
}

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"
}

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\BlocklistMonitoringUpdateParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->blocklistMonitoring->update(
    'monitor-id',
    (new BlocklistMonitoringUpdateParams())
        ->setName('Updated Name')
        ->setNotify(true)
        ->setNotifyEmail('alerts@example.com')
);

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.blocklistMonitor.update("monitor_id", {
  name: "Updated Name",
  notify: true,
  notify_email: "alerts@example.com",
})
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.blocklistmonitoring.BlocklistMonitor;
import com.mailersend.sdk.exceptions.MailerSendException;

public void updateBlocklistMonitor() {

    MailerSend ms = new MailerSend();
    ms.setToken("Your API token");

    try {

        BlocklistMonitor monitor = ms.blocklistMonitoring().updateMonitorBuilder()
                .name("Updated Name")
                .notify(true)
                .notifyEmail("alerts@example.com")
                .updateMonitor("your-monitor-id");

        System.out.println(monitor.id);
        System.out.println(monitor.name);
        System.out.println(monitor.notify);

    } catch (MailerSendException e) {
        e.printStackTrace();
    }
}

Responses

Valid

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

The response has the same shape as the Get a monitor response, without the hits and children arrays.

Error

Response Code: 404 Not Found

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.

use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->blocklistMonitoring->delete('monitor-id');

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.blocklistMonitor.delete("monitor_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;

public void deleteBlocklistMonitor() {

    MailerSend ms = new MailerSend();
    ms.setToken("Your API token");

    try {

        boolean deleted = ms.blocklistMonitoring().deleteMonitor("your-monitor-id");

        System.out.println("Monitor deleted: " + deleted);

    } catch (MailerSendException e) {
        e.printStackTrace();
    }
}

Responses

Valid

Response Code: 204 No Content

Error

Response Code: 404 Not Found

DMARC Monitoring

Receive and analyze DMARC reports and identify potential sending issues with MailerSend's DMARC Monitoring API. Create and fetch monitors and retrieve your DMARC reports.

Get a head start on your integration

Get started with MailerSend API integration for seamless email communication. Explore our guides and take your transactional email to the next level.