> ## 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.

# Build a sender profile with the API

> Use POST /senderprofile to get a sender's message counts over time and check whether MailChannels is blocking them, with worked examples in PHP, Python, and Node.js.

`POST /senderprofile` returns the data behind the [Sender Profile](https://docs.mailchannels.com/outbound/sender-profiles.md) 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`](https://docs.mailchannels.com/outbound/log-search-api/alerts) to see why.

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

## Find the sender ID

The profile is keyed by the full [sender ID](https://docs.mailchannels.com/outbound/api-reference-introduction.md#sender-ids), 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:

```json theme={null}
{
  "sender": "alice@example.com",
  "start_date": "2026-11-12",
  "end_date": "2026-11-18"
}
```

## Request a sender profile

```bash cURL theme={null}
curl -X POST "https://api.mailchannels.net/outbound/v1/senderprofile" \
  -H "X-API-KEY: $MAILCHANNELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "senderid": "examplehost|x-authuser|alice@example.com",
    "start_date": "2026-11-12T00:00:00+00:00",
    "end_date": "2026-11-18T23:59:59+00:00",
    "interval": "days"
  }'
```

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

import requests

response = requests.post(
    "https://api.mailchannels.net/outbound/v1/senderprofile",
    headers={"X-API-KEY": os.environ["MAILCHANNELS_API_KEY"]},
    json={
        "senderid": "examplehost|x-authuser|alice@example.com",
        "start_date": "2026-11-12T00:00:00+00:00",
        "end_date": "2026-11-18T23:59:59+00:00",
        "interval": "days"
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

```javascript Node.js theme={null}
const response = await fetch("https://api.mailchannels.net/outbound/v1/senderprofile", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.MAILCHANNELS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "senderid": "examplehost|x-authuser|alice@example.com",
    "start_date": "2026-11-12T00:00:00+00:00",
    "end_date": "2026-11-18T23:59:59+00:00",
    "interval": "days"
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());
```

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

$ch = curl_init('https://api.mailchannels.net/outbound/v1/senderprofile');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'X-API-KEY: ' . getenv('MAILCHANNELS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'senderid' => 'examplehost|x-authuser|alice@example.com',
        'start_date' => '2026-11-12T00:00:00+00:00',
        'end_date' => '2026-11-18T23:59:59+00:00',
        'interval' => 'days',
    ]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status !== 200) {
    throw new RuntimeException("HTTP $status: $body");
}
print_r(json_decode($body, true));
```

### Request fields

| Field | Required | Description |
| - | - | - |
| `senderid` | Yes | The full sender ID. |
| `start_date` | Yes | Start of the range. Use `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS`, or `YYYY-MM-DDTHH:MM:SS+00:00`, in UTC. |
| `end_date` | Yes | End of the range, in the same formats. Must be on or after `start_date`. If the time is omitted or is midnight, the whole day is included. |
| `interval` | No | `hours`, `days`, or `weeks`. Defaults to `days`. |

> [!NOTE]
>
> The request field is `senderid`, with no underscore. The other endpoints use `sender_id`.

## Read the response

```json theme={null}
{
  "counts": {
    "2026.11.16 00:00:00Z": { "queued": 2873, "sent": 1104, "delivered": 1062, "blocked": 1769, "rejected": 42 },
    "2026.11.17 00:00:00Z": { "queued": 4120, "sent": 915, "delivered": 880, "blocked": 3205, "rejected": 35 }
  },
  "policyDisposition": "Sender was rejected by policy. Message: 550 5.7.1 [ESA] Blocked. See https://console.mailchannels.net/insights/bounce?..."
}
```

### 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.

| Field | Meaning |
| - | - |
| `queued` | Messages MailChannels received from the sender. |
| `sent` | Messages MailChannels accepted for delivery. |
| `delivered` | Messages the recipient's mail server accepted. |
| `blocked` | Messages MailChannels rejected with a 5xx response, for example because they were spam or the sender was blocked. |
| `rejected` | Messages the recipient's mail server rejected with a 5xx response. |

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:

| Starts with | Meaning |
| - | - |
| `Sender was accepted by policy.` | The sender is not blocked. |
| `Sender was rejected by policy.` | The sender is blocked. The SMTP response follows `Message:`. |
| `Sender was deferred by policy.` | The sender's messages are being temporarily deferred. |
| `Unable to retrieve policy disposition.` | The disposition could not be checked. The counts are still returned. Try again later. |

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](https://docs.mailchannels.com/outbound/log-search-api/delist-senders.md) after you secure the account.

## Choose an interval

| Interval | Good for |
| - | - |
| `hours` | Pinpointing when an abuse campaign started, over a range of a few days. |
| `days` | A weekly or monthly view of a sender's traffic. This is the default. |
| `weeks` | Long-term trends over several months. |

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.

```python Python theme={null}
"""Print a 7-day profile for one sender: daily counts, policy status, and alerts.

Usage: python sender_profile.py "examplehost|x-authuser|alice@example.com"
"""
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 post(path, payload):
    response = session.post(f"{BASE_URL}{path}", json=payload, timeout=30)
    response.raise_for_status()
    return response.json()


def main():
    sender_id = sys.argv[1]

    # Use UTC timestamps with an explicit offset. Both endpoints accept this format.
    now = datetime.now(timezone.utc).replace(microsecond=0)
    start = (now - timedelta(days=6)).replace(hour=0, minute=0, second=0)
    date_range = {"start_date": start.isoformat(), "end_date": now.isoformat()}

    profile = post("/senderprofile", {"senderid": sender_id, "interval": "days", **date_range})
    alerts = post("/alerts", {"sender_id": sender_id, **date_range})

    print(f"Sender ID: {sender_id}")
    print(f"Policy:    {profile['policyDisposition']}\n")

    fields = ["queued", "sent", "delivered", "blocked", "rejected"]
    totals = dict.fromkeys(fields, 0)
    print(f"{'Period (UTC)':<22}" + "".join(f"{f:>11}" for f in fields))
    # Keys look like "2026.11.13 00:00:00Z" and sort chronologically as strings.
    for period in sorted(profile["counts"]):
        counts = profile["counts"][period]
        print(f"{period:<22}" + "".join(f"{counts[f]:>11}" for f in fields))
        for f in fields:
            totals[f] += counts[f]
    print(f"{'Total':<22}" + "".join(f"{totals[f]:>11}" for f in fields))

    if totals["queued"]:
        print(f"\nBlocked by MailChannels: {totals['blocked'] / totals['queued']:.1%} of messages received")

    print(f"\nAlerts: {len(alerts)}")
    for alert in sorted(alerts, key=lambda a: a["timestamp"]):
        print(f"  {alert['timestamp']}  {alert['condition_name']:<22} "
              f"{alert.get('envelope_sender', '')} {alert.get('ip_address', '')}")

    if profile["policyDisposition"].startswith("Sender was rejected"):
        print("\nThis sender is currently blocked. See the sender delisting guide.")


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

```javascript Node.js theme={null}
// Print a 7-day profile for one sender: daily counts, policy status, and alerts.
//
// Usage: node sender_profile.mjs "examplehost|x-authuser|alice@example.com"
//        (requires Node.js 18+)

const API_KEY = process.env.MAILCHANNELS_API_KEY;
const BASE_URL = "https://api.mailchannels.net/outbound/v1";

async function post(path, payload) {
  const response = await fetch(`${BASE_URL}${path}`, {
    method: "POST",
    headers: { "X-API-KEY": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
  if (!response.ok) {
    throw new Error(`${path} failed with HTTP ${response.status}: ${await response.text()}`);
  }
  return response.json();
}

// Format a Date as "2026-11-13T00:00:00+00:00". Both endpoints accept this format.
const utc = (d) => d.toISOString().slice(0, 19) + "+00:00";

const senderId = process.argv[2];
const now = new Date();
const start = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() - 6));
const dateRange = { start_date: utc(start), end_date: utc(now) };

const [profile, alerts] = await Promise.all([
  post("/senderprofile", { senderid: senderId, interval: "days", ...dateRange }),
  post("/alerts", { sender_id: senderId, ...dateRange }),
]);

console.log(`Sender ID: ${senderId}`);
console.log(`Policy:    ${profile.policyDisposition}\n`);

const fields = ["queued", "sent", "delivered", "blocked", "rejected"];
const totals = Object.fromEntries(fields.map((f) => [f, 0]));
const row = (label, values) =>
  label.padEnd(22) + fields.map((f) => String(values[f]).padStart(11)).join("");

console.log("Period (UTC)".padEnd(22) + fields.map((f) => f.padStart(11)).join(""));
// Keys look like "2026.11.13 00:00:00Z" and sort chronologically as strings.
for (const period of Object.keys(profile.counts).sort()) {
  const counts = profile.counts[period];
  console.log(row(period, counts));
  for (const f of fields) totals[f] += counts[f];
}
console.log(row("Total", totals));

if (totals.queued > 0) {
  const rate = ((100 * totals.blocked) / totals.queued).toFixed(1);
  console.log(`\nBlocked by MailChannels: ${rate}% of messages received`);
}

console.log(`\nAlerts: ${alerts.length}`);
for (const alert of alerts.sort((a, b) => a.timestamp.localeCompare(b.timestamp))) {
  console.log(`  ${alert.timestamp}  ${alert.condition_name.padEnd(22)} ` +
    `${alert.envelope_sender ?? ""} ${alert.ip_address ?? ""}`);
}

if (profile.policyDisposition.startsWith("Sender was rejected")) {
  console.log("\nThis sender is currently blocked. See the sender delisting guide.");
}
```

```php PHP theme={null}
<?php
// Print a 7-day profile for one sender: daily counts, policy status, and alerts.
//
// Usage: php sender_profile.php 'examplehost|x-authuser|alice@example.com'
//        (requires ext-curl)

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

function post(string $path, array $payload): array
{
    $ch = curl_init(BASE_URL . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTPHEADER => [
            'X-API-KEY: ' . getenv('MAILCHANNELS_API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode($payload),
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($body === false || $status !== 200) {
        throw new RuntimeException("$path failed with HTTP $status: " . ($body ?: curl_error($ch)));
    }
    return json_decode($body, true);
}

$senderId = $argv[1];

// Use UTC timestamps with an explicit offset. Both endpoints accept this format.
$now = new DateTimeImmutable('now', new DateTimeZone('UTC'));
$start = $now->modify('-6 days')->setTime(0, 0);
$dateRange = ['start_date' => $start->format('Y-m-d\TH:i:sP'), 'end_date' => $now->format('Y-m-d\TH:i:sP')];

$profile = post('/senderprofile', ['senderid' => $senderId, 'interval' => 'days'] + $dateRange);
$alerts = post('/alerts', ['sender_id' => $senderId] + $dateRange);

echo "Sender ID: $senderId\n";
echo "Policy:    {$profile['policyDisposition']}\n\n";

$fields = ['queued', 'sent', 'delivered', 'blocked', 'rejected'];
$totals = array_fill_keys($fields, 0);
$row = fn (string $label, array $values) =>
    str_pad($label, 22) . implode('', array_map(fn ($f) => str_pad((string) $values[$f], 11, ' ', STR_PAD_LEFT), $fields));

echo str_pad('Period (UTC)', 22) . implode('', array_map(fn ($f) => str_pad($f, 11, ' ', STR_PAD_LEFT), $fields)) . "\n";
// Keys look like "2026.11.13 00:00:00Z" and sort chronologically as strings.
$counts = $profile['counts'];
ksort($counts);
foreach ($counts as $period => $periodCounts) {
    echo $row($period, $periodCounts) . "\n";
    foreach ($fields as $f) {
        $totals[$f] += $periodCounts[$f];
    }
}
echo $row('Total', $totals) . "\n";

if ($totals['queued'] > 0) {
    printf("\nBlocked by MailChannels: %.1f%% of messages received\n", 100 * $totals['blocked'] / $totals['queued']);
}

echo "\nAlerts: " . count($alerts) . "\n";
usort($alerts, fn ($a, $b) => strcmp($a['timestamp'], $b['timestamp']));
foreach ($alerts as $alert) {
    printf("  %s  %-22s %s %s\n", $alert['timestamp'], $alert['condition_name'],
        $alert['envelope_sender'] ?? '', $alert['ip_address'] ?? '');
}

if (str_starts_with($profile['policyDisposition'], 'Sender was rejected')) {
    echo "\nThis sender is currently blocked. See the sender delisting guide.\n";
}
```

Run it with a sender ID:

```bash Python theme={null}
python sender_profile.py "examplehost|x-authuser|alice@example.com"
```

```bash Node.js theme={null}
node sender_profile.mjs "examplehost|x-authuser|alice@example.com"
```

```bash PHP theme={null}
php sender_profile.php "examplehost|x-authuser|alice@example.com"
```

The output for a compromised account looks like this:

```text theme={null}
Sender ID: examplehost|x-authuser|alice@example.com
Policy:    Sender was rejected by policy. Message: 550 5.7.1 [ESA] Blocked. See https://console.mailchannels.net/insights/bounce?...

Period (UTC)               queued       sent  delivered    blocked   rejected
2026.11.13 00:00:00Z          412        398        391         14          7
2026.11.14 00:00:00Z          388        377        370         11          7
2026.11.15 00:00:00Z          405        393        384         12          9
2026.11.16 00:00:00Z         2873       1104       1062       1769         42
2026.11.17 00:00:00Z         4120        915        880       3205         35
2026.11.18 00:00:00Z         1290        212        204       1078          8
2026.11.19 00:00:00Z           96          0          0         96          0
Total                        9584       3399       3291       6185        108

Blocked by MailChannels: 64.5% of messages received

Alerts: 0

This sender is currently blocked. See the sender delisting guide.
```

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](https://docs.mailchannels.com/outbound/log-search-api/search-logs.md) for the sender ID
with `"spam_disposition": "CONFIRMED"`.

## Next steps

* [Delist the sender](https://docs.mailchannels.com/outbound/log-search-api/delist-senders.md) once the account is secure.
* [Query alerts](https://docs.mailchannels.com/outbound/log-search-api/alerts.md) to filter by alert type or IP address.
* See the [`POST /senderprofile` reference](https://docs.mailchannels.com/api-reference/get-sender-profile) for the full schema.


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