Skip to main content
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.net bounce?
  • Which messages from this sender were blocked in the last week?
  • Can this blocked sender be delisted through the API?
Before you start, read Before you begin.

Make a search request

Send your filters as a JSON object in the request body. Set count 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.
Text filters such as sender, rcpt, and subject use full-text matching, so results can include partial matches. When you need an exact match, compare the returned field in your code, as the delisting example does.

Common filter combinations

Read rspcode and rspmsg in each result. A message blocked by MailChannels has a response code in brackets, such as [ESA] or [CS], in rspmsg.
Results with "remediation_options": "DELIST" can be passed to POST /remediation.

Response fields

The response is a JSON object. Matching entries are in the results 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 increase start_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.
Run it with a sender ID and a date range:
The output looks like this:
undelivered.csv

Next steps