Skip to main content
POST /senderprofile returns the data behind the Sender Profile page in the Host Console. For one sender ID, it returns:
  • Message counts grouped by hour, day, or week, so you can see when a sender’s volume or block rate changed.
  • The policy disposition, which tells you whether MailChannels currently accepts, rejects, or defers that sender.
Use it to answer questions like “Is this customer blocked right now?” and “When did this account start sending spam?” Combine it with POST /alerts to see why. Before you start, read Before you begin.

Find the sender ID

The profile is keyed by the full sender ID, such as examplehost|x-authuser|alice@example.com. The value must match exactly. If you only know the sender’s email address, search the logs for one of their messages and read the sender_id field:

Request a sender profile

Request fields

The request field is senderid, with no underscore. The other endpoints use sender_id.

Read the response

Counts

counts is an object keyed by the start of each period, in the format YYYY.MM.DD HH:MM:SSZ. JSON objects are unordered, so sort the keys before you display them. The keys sort correctly as plain strings. Periods with no traffic may be missing, so treat a missing period as zero. Two ratios are useful:
  • blocked / queued shows how much of the sender’s traffic MailChannels is stopping. A sudden rise usually means the account is compromised or the sender has been blocked.
  • rejected / sent shows how often recipients’ mail servers refuse the sender’s mail. A high value often points to a poor list or a reputation problem.

Policy disposition

policyDisposition is a sentence that describes how MailChannels policy treats the sender right now, regardless of the date range you asked for. It starts with one of these phrases: When the sender is rejected, the bracketed code in the message tells you why. An [ESA] code means the sender ID is on the MailChannels blocklist. You can remove that block with the delisting endpoint after you secure the account.

Choose an interval

Counts are grouped in UTC. Send your dates in UTC (with no offset, or with +00:00) so the period keys line up with your date range.

Worked example: sender report

This script prints a 7-day report for one sender. It requests the sender profile and the sender’s alerts for the same date range, then prints daily counts, totals, the block rate, the policy disposition, and each alert.
Run it with a sender ID:
The output for a compromised account looks like this:
In this example, volume jumped on November 16 and most of it was blocked. To find the hour the campaign started, run the same request for November 15 to 16 with "interval": "hours". To see the messages themselves, search the logs for the sender ID with "spam_disposition": "CONFIRMED".

Next steps