> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailchannels.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Delist a blocked sender with the API

> Use POST /remediation to remove a sender from a MailChannels blocklist after you secure the account, with worked examples in PHP, Python, and Node.js.

When MailChannels sees confirmed abuse from a sender, it can add the sender to a blocklist. Every
message the sender tries to send is then rejected with SMTP code `550`. Once you have secured the
account, `POST /remediation` lets you remove the block yourself, without opening a support ticket.
This is the API equivalent of the **Delist Sender** button described in
[Unblock senders](https://docs.mailchannels.com/outbound/unblock-senders.md).

Before you start, read [Before you begin](https://docs.mailchannels.com/outbound/api-reference-introduction.md#before-you-begin).

> [!WARNING]
>
> Secure the account before you delist it. Change the password, remove any malware, and stop the
> spam. If the abuse continues, MailChannels blocks the sender again. See
> [Best practices before unblocking](https://docs.mailchannels.com/outbound/unblock-senders.md#best-practices-before-unblocking).

## Which blocks you can remove

The API can remove three kinds of block. The code in brackets appears in the rejection message
(`rspmsg`) of the blocked messages.

| Code | What is blocked | What delisting removes |
| - | - | - |
| `ESA` | The sender ID | The sender ID, for example `examplehost\|x-authuser\|alice@example.com`. |
| `SB01` | The envelope sender address | The address, for example `alice@example.com`. |
| `SB02` | The envelope sender domain | The whole domain, for example `example.com`. This unblocks every address at that domain. |

Other rejections, such as content spam blocks (`[CS]`), cannot be removed through the API. For
those, see [Unblock senders](https://docs.mailchannels.com/outbound/unblock-senders.md).

## How delisting works

When you call `POST /remediation`, MailChannels:

1. Looks for the most recent message that matches your `message_id` or `sender`, was not delivered,
   and was rejected with SMTP code `550` in the **last 7 days**.
2. Reads the block code from that message's rejection.
3. Removes the sender ID, address, or domain from the matching blocklist.

Because of step 1, the sender must have tried to send at least one message in the last 7 days.
If they have not, there is nothing to look up, and you get a `404`.

## Delist a sender

**1. Find a blocked message**

Search for the sender's rejected messages from the last 7 days:

```json theme={null}
{
  "sender": "alice@example.com",
  "delivered": "N",
  "rspcode": 550,
  "start_date": "2026-11-13",
  "end_date": "2026-11-19"
}
```

Pick the newest result whose `remediation_options` is `DELIST`, and note its `message_id`. If
no result has `remediation_options`, the block cannot be removed through the API.

`remediation_options` shows that the block type can be delisted. It does not show whether the
block is still in place. To check that, use the `policyDisposition` from
[`POST /senderprofile`](https://docs.mailchannels.com/outbound/log-search-api/sender-profiles#policy-disposition).

**2. Secure the account**

Work with your customer to fix the cause of the abuse before you continue.

**3. Request delisting**

Send the message ID as the `message_id` query parameter. URL-encode it, because message IDs
contain characters such as `<`, `>`, and `@`. There is no request body.

```bash cURL theme={null}
curl -X POST "https://api.mailchannels.net/outbound/v1/remediation?message_id=%3C20261118101500.4f2a9c%40mail.example.com%3E" \
  -H "X-API-KEY: $MAILCHANNELS_API_KEY"
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.mailchannels.net/outbound/v1/remediation",
    headers={"X-API-KEY": os.environ["MAILCHANNELS_API_KEY"]},
    params={
        "message_id": "<20261118101500.4f2a9c@mail.example.com>"
    },
    timeout=30,
)

# 200: delisted; 404: no eligible block found
print(response.status_code)
```

```javascript Node.js theme={null}
const params = new URLSearchParams({
  "message_id": "<20261118101500.4f2a9c@mail.example.com>"
});
const response = await fetch(`https://api.mailchannels.net/outbound/v1/remediation?${params}`, {
  method: "POST",
  headers: { "X-API-KEY": process.env.MAILCHANNELS_API_KEY },
});

// 200: delisted; 404: no eligible block found
console.log(response.status);
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api.mailchannels.net/outbound/v1/remediation' . '?' . http_build_query([
    'message_id' => '<20261118101500.4f2a9c@mail.example.com>',
]));
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => ['X-API-KEY: ' . getenv('MAILCHANNELS_API_KEY')],
    CURLOPT_POSTFIELDS => '',
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// 200: delisted; 404: no eligible block found
echo $status, "\n";
```

**4. Check the result**

A `200` response means the block was removed. See [Responses](#responses) for the other codes.

> [!TIP]
>
> You can pass `sender` instead of `message_id`. MailChannels then uses the sender's most recent
> `550` rejection. If that rejection was not caused by a delistable block, the request fails even
> when an older message was. Using `message_id` lets you choose the exact message.

## Responses

| Status | Meaning | What to do |
| - | - | - |
| `200` | The block was removed. The body is `null`. | Ask the customer to resend. |
| `400` | Neither `message_id` nor `sender` was provided. | Add one of them. |
| `404` | No message rejected with `550` in the last 7 days matched, or the blocklist entry was not found. | Check the message ID. Use the sender profile to confirm the sender is still blocked. |
| `500` | The block on the matching message cannot be removed through the API, or an internal error occurred. | Check that the message has `remediation_options: DELIST`. If it does, retry later or contact [support@mailchannels.com](mailto:support@mailchannels.com). |

Only `400` responses include an error message. For the others, rely on the status code.

## Worked example

This script finds the newest delistable block for a sender address and prints its details. Run it
without `--confirm` to check what would be delisted. Run it again with `--confirm` to request
delisting.

The script compares `sender` exactly, because the search filter uses full-text matching and can
return similar addresses.

```python Python theme={null}
"""Find a recent block for a sender and request delisting.

Usage: python delist_sender.py alice@example.com            # dry run
       python delist_sender.py alice@example.com --confirm  # delist

Secure the account before you delist it. Otherwise it is blocked again.
"""
import os
import sys
from datetime import datetime, timedelta, timezone

import requests

API_KEY = os.environ["MAILCHANNELS_API_KEY"]
BASE_URL = "https://api.mailchannels.net/outbound/v1"

session = requests.Session()
session.headers.update({"X-API-KEY": API_KEY})


def find_delistable_block(sender):
    """Return the newest delistable rejection for this sender from the last 7 days."""
    today = datetime.now(timezone.utc).date()
    response = session.post(
        f"{BASE_URL}/search",
        params={"count": 100},
        json={
            "sender": sender,
            "delivered": "N",
            "rspcode": 550,
            "start_date": (today - timedelta(days=6)).isoformat(),
            "end_date": today.isoformat(),
        },
        timeout=30,
    )
    response.raise_for_status()
    for result in response.json().get("results", []):  # newest first
        if result.get("sender", "").lower() == sender.lower() \
                and result.get("remediation_options") == "DELIST":
            return result
    return None


def request_delisting(message_id):
    response = session.post(f"{BASE_URL}/remediation", params={"message_id": message_id}, timeout=30)
    if response.status_code == 200:
        return "Delisting request completed."
    if response.status_code == 404:
        return "No eligible block found. The sender may already be delisted."
    if response.status_code == 400:
        return f"Bad request: {response.json().get('message')}"
    response.raise_for_status()
    return f"Unexpected status {response.status_code}"


def main():
    sender = sys.argv[1]
    confirm = "--confirm" in sys.argv[2:]

    block = find_delistable_block(sender)
    if block is None:
        print(f"No delistable block for {sender} in the last 7 days.")
        print("If the sender is still blocked, contact MailChannels Support.")
        return

    print(f"Blocked at: {block['@timestamp']}")
    print(f"Sender ID:  {block.get('sender_id', '')}")
    print(f"Response:   {block.get('rspcode')} {block.get('rspmsg')}")
    print(f"Message ID: {block['message_id']}")

    if not confirm:
        print("\nDry run. Secure the account, then re-run with --confirm to delist.")
        return

    print("\n" + request_delisting(block["message_id"]))


if __name__ == "__main__":
    main()
```

```javascript Node.js theme={null}
// Find a recent block for a sender and request delisting.
//
// Usage: node delist_sender.mjs alice@example.com            # dry run
//        node delist_sender.mjs alice@example.com --confirm  # delist
//
// Secure the account before you delist it. Otherwise it is blocked again.
// Requires Node.js 18+.

const API_KEY = process.env.MAILCHANNELS_API_KEY;
const BASE_URL = "https://api.mailchannels.net/outbound/v1";
const headers = { "X-API-KEY": API_KEY, "Content-Type": "application/json" };

// Return the newest delistable rejection for this sender from the last 7 days.
async function findDelistableBlock(sender) {
  const today = new Date();
  const weekAgo = new Date(today);
  weekAgo.setUTCDate(today.getUTCDate() - 6);
  const response = await fetch(`${BASE_URL}/search?count=100`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      sender,
      delivered: "N",
      rspcode: 550,
      start_date: weekAgo.toISOString().slice(0, 10),
      end_date: today.toISOString().slice(0, 10),
    }),
  });
  if (!response.ok) {
    throw new Error(`Search failed with HTTP ${response.status}: ${await response.text()}`);
  }
  const { results = [] } = await response.json(); // newest first
  return results.find(
    (r) => r.sender?.toLowerCase() === sender.toLowerCase() && r.remediation_options === "DELIST",
  );
}

async function requestDelisting(messageId) {
  const url = `${BASE_URL}/remediation?message_id=${encodeURIComponent(messageId)}`;
  const response = await fetch(url, { method: "POST", headers: { "X-API-KEY": API_KEY } });
  switch (response.status) {
    case 200:
      return "Delisting request completed.";
    case 404:
      return "No eligible block found. The sender may already be delisted.";
    case 400:
      return `Bad request: ${(await response.json()).message}`;
    default:
      throw new Error(`Delisting failed with HTTP ${response.status}`);
  }
}

const [sender, ...flags] = process.argv.slice(2);
const block = await findDelistableBlock(sender);

if (!block) {
  console.log(`No delistable block for ${sender} in the last 7 days.`);
  console.log("If the sender is still blocked, contact MailChannels Support.");
} else {
  console.log(`Blocked at: ${block["@timestamp"]}`);
  console.log(`Sender ID:  ${block.sender_id ?? ""}`);
  console.log(`Response:   ${block.rspcode} ${block.rspmsg}`);
  console.log(`Message ID: ${block.message_id}`);

  if (!flags.includes("--confirm")) {
    console.log("\nDry run. Secure the account, then re-run with --confirm to delist.");
  } else {
    console.log("\n" + (await requestDelisting(block.message_id)));
  }
}
```

```php PHP theme={null}
<?php
// Find a recent block for a sender and request delisting.
//
// Usage: php delist_sender.php alice@example.com            # dry run
//        php delist_sender.php alice@example.com --confirm  # delist
//
// Secure the account before you delist it. Otherwise it is blocked again.
// Requires ext-curl.

const BASE_URL = 'https://api.mailchannels.net/outbound/v1';

/** Send a POST request and return [status, decoded body]. */
function apiPost(string $url, ?array $payload = null): array
{
    $headers = ['X-API-KEY: ' . getenv('MAILCHANNELS_API_KEY')];
    $ch = curl_init($url);
    curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30]);
    if ($payload !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    } else {
        curl_setopt($ch, CURLOPT_POSTFIELDS, '');
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $body = curl_exec($ch);
    if ($body === false) {
        throw new RuntimeException(curl_error($ch));
    }
    return [curl_getinfo($ch, CURLINFO_HTTP_CODE), json_decode($body, true)];
}

/** Return the newest delistable rejection for this sender from the last 7 days. */
function findDelistableBlock(string $sender): ?array
{
    $today = new DateTimeImmutable('now', new DateTimeZone('UTC'));
    [$status, $data] = apiPost(BASE_URL . '/search?count=100', [
        'sender' => $sender,
        'delivered' => 'N',
        'rspcode' => 550,
        'start_date' => $today->modify('-6 days')->format('Y-m-d'),
        'end_date' => $today->format('Y-m-d'),
    ]);
    if ($status !== 200) {
        throw new RuntimeException("Search failed with HTTP $status");
    }
    foreach ($data['results'] ?? [] as $result) { // newest first
        if (strcasecmp($result['sender'] ?? '', $sender) === 0
            && ($result['remediation_options'] ?? '') === 'DELIST') {
            return $result;
        }
    }
    return null;
}

function requestDelisting(string $messageId): string
{
    [$status, $data] = apiPost(BASE_URL . '/remediation?' . http_build_query(['message_id' => $messageId]));
    return match ($status) {
        200 => 'Delisting request completed.',
        404 => 'No eligible block found. The sender may already be delisted.',
        400 => 'Bad request: ' . ($data['message'] ?? ''),
        default => throw new RuntimeException("Delisting failed with HTTP $status"),
    };
}

$sender = $argv[1];
$confirm = in_array('--confirm', array_slice($argv, 2), true);

$block = findDelistableBlock($sender);
if ($block === null) {
    echo "No delistable block for $sender in the last 7 days.\n";
    echo "If the sender is still blocked, contact MailChannels Support.\n";
    exit(0);
}

echo "Blocked at: {$block['@timestamp']}\n";
echo 'Sender ID:  ' . ($block['sender_id'] ?? '') . "\n";
echo "Response:   {$block['rspcode']} {$block['rspmsg']}\n";
echo "Message ID: {$block['message_id']}\n";

if (!$confirm) {
    echo "\nDry run. Secure the account, then re-run with --confirm to delist.\n";
    exit(0);
}

echo "\n" . requestDelisting($block['message_id']) . "\n";
```

First, do a dry run:

```bash Python theme={null}
python delist_sender.py alice@example.com
```

```bash Node.js theme={null}
node delist_sender.mjs alice@example.com
```

```bash PHP theme={null}
php delist_sender.php alice@example.com
```

```text theme={null}
Blocked at: 2026-11-19T09:12:44.000Z
Sender ID:  examplehost|x-authuser|alice@example.com
Response:   550 5.7.1 [ESA] Blocked. See https://console.mailchannels.net/insights/bounce?...
Message ID: <20261119091244.7d3e1a@mail.example.com>

Dry run. Secure the account, then re-run with --confirm to delist.
```

After you have secured the account, add `--confirm`:

```text theme={null}
Blocked at: 2026-11-19T09:12:44.000Z
Sender ID:  examplehost|x-authuser|alice@example.com
Response:   550 5.7.1 [ESA] Blocked. See https://console.mailchannels.net/insights/bounce?...
Message ID: <20261119091244.7d3e1a@mail.example.com>

Delisting request completed.
```

## Troubleshooting

> [accordion] The search finds blocked messages, but none has remediation\_options
>
> The messages were rejected by a block that the API cannot remove, such as a content spam block.
> Follow [Unblock senders](https://docs.mailchannels.com/outbound/unblock-senders.md) instead.

> [accordion] I get a 404 even though the sender is blocked
>
> The sender has not tried to send in the last 7 days, so there is no rejected message to look up.
> Ask the customer to send one test message, then try again with the new message ID.

> [accordion] The sender is blocked again soon after delisting
>
> The abuse has not stopped. Use the [sender report](https://docs.mailchannels.com/outbound/log-search-api/sender-profiles.md#worked-example-sender-report)
> to see the sender's traffic, and secure the account before you delist it again. If the sender
> keeps being blocked, contact [support@mailchannels.com](mailto:support@mailchannels.com).

## Next steps

* [Build a sender profile](https://docs.mailchannels.com/outbound/log-search-api/sender-profiles.md) to watch the sender after delisting.
* Read [Unblock senders](https://docs.mailchannels.com/outbound/unblock-senders.md) for blocks that the API cannot remove.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.