Skip to main content
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. Before you start, read Before you begin.
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.

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. Other rejections, such as content spam blocks ([CS]), cannot be removed through the API. For those, see Unblock senders.

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:
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.
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.
4

Check the result

A 200 response means the block was removed. See Responses for the other codes.
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

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.
First, do a dry run:
After you have secured the account, add --confirm:

Troubleshooting

The messages were rejected by a block that the API cannot remove, such as a content spam block. Follow Unblock senders instead.
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.
The abuse has not stopped. Use the 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.

Next steps