POST /search returns the delivery log entries for your account that match your filters.
Each entry tells you who sent the message, who it was for, and how MailChannels or the recipient’s
mail server responded. Use it to answer questions like:
- Why did my customer’s message to
bob@example.netbounce? - Which messages from this sender were blocked in the last week?
- Can this blocked sender be delisted through the API?
Make a search request
Send your filters as a JSON object in the request body. Setcount and start_at as query parameters.
Always send a JSON object as the request body. To search without filters, send
{}. A request
with no body returns 400 Bad Request.Filters
All filters are optional. When you use more than one, a log entry must match all of them.
If you omit
start_date and end_date, the API searches the last 3 days and adds a notice
field to the response to remind you.
Common filter combinations
Why did a message to a specific recipient fail?
Why did a message to a specific recipient fail?
rspcode and rspmsg in each result. A message blocked by MailChannels has a response
code in brackets, such as [ESA] or [CS], in rspmsg.Find one message by its Message-ID
Find one message by its Message-ID
List messages from a sender that MailChannels classified as spam
List messages from a sender that MailChannels classified as spam
Find blocks that you can remove through the API
Find blocks that you can remove through the API
"remediation_options": "DELIST" can be passed to
POST /remediation.Response fields
The response is a JSON object. Matching entries are in theresults array, newest first.
When nothing matches, results is omitted, so treat a missing results field as an empty list.
Fields with no value are also omitted from each entry.
Get more than one page of results
Each request returns at most 100 results. To get more, repeat the request and increasestart_at
by count each time. Stop when a page has fewer results than you asked for.
The API can return at most 9,999 results for a single search, because start_at + count cannot
exceed 9,999. If a search could match more than that, split it into smaller date ranges, such as
one day at a time.
Worked example: export undelivered messages to CSV
This script exports every undelivered message for one sender ID to CSV. It searches one day at a time and pages through each day, so it is not limited to 9,999 results in total.undelivered.csv
Next steps
- Build a sender profile to see a sender’s traffic over time.
- Delist a blocked sender once the account is secure.
- See the
POST /searchreference for the full schema.

