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

# Query alerts with the API

> Use POST /alerts and POST /alertcount to list and count the alerts raised for a sender, with examples in PHP, Python, and Node.js.

MailChannels raises an alert when a sender trips one of your [monitors](https://docs.mailchannels.com/outbound/monitors-alerts.md),
for example when it starts sending spam or is added to a blocklist. The Log Search API gives you two
ways to read those alerts for a sender:

* `POST /alerts` lists each alert.
* `POST /alertcount` counts alerts by hour, day, or week.

If you want to react to alerts as they happen, use [webhooks](https://docs.mailchannels.com/outbound/webhooks.md) instead. Use these
endpoints to look back at a sender's history, for example when you investigate an abuse report.

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

## List alerts

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

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

import requests

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

```javascript Node.js theme={null}
const response = await fetch("https://api.mailchannels.net/outbound/v1/alerts", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.MAILCHANNELS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "sender_id": "examplehost|x-authuser|alice@example.com",
    "start_date": "2026-11-12T00:00:00+00:00",
    "end_date": "2026-11-18T23:59:59+00:00"
  }),
});
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/alerts');
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([
        'sender_id' => 'examplehost|x-authuser|alice@example.com',
        'start_date' => '2026-11-12T00:00:00+00:00',
        'end_date' => '2026-11-18T23:59:59+00:00',
    ]),
]);
$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 |
| - | - | - |
| `sender_id` | Yes | The full [sender ID](https://docs.mailchannels.com/outbound/api-reference-introduction.md#sender-ids). |
| `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`. |
| `condition_name` | No | Only return alerts of this type. See [Alert types](#alert-types). |
| `ip_address` | No | Only return alerts for this IP address. An invalid IP address is ignored. |
| `env_sender` | No | Only return alerts for this envelope sender address. |
| `env_sender_domain` | No | Only return alerts for this envelope sender domain. |
| `sub_account_filter` | No | `parent` returns alerts for your own account only. `subaccount` returns alerts for your sub-accounts only. Omit it to return both. |

### Response

The response is a JSON array of alerts. It is empty when there are no alerts.

| Field | Description |
| - | - |
| `timestamp` | When the alert was raised. |
| `condition_name` | The alert type. |
| `condition` | Details of the monitor condition that raised the alert, including its `description`. |
| `sender_id` | The sender ID. |
| `envelope_sender` | The envelope sender address, if the alert has one. |
| `ip_address` | The IP address, if the alert has one. |
| `auth_id` | The account the alert belongs to. |
| `parent` | The parent account, when the alert belongs to a sub-account. Otherwise `null`. |

### Alert types

Use these values for `condition_name`:

| Value | Alert |
| - | - |
| `SENDING_SPAM` | The sender ID is sending spam. |
| `INVALID_RECIPIENTS` | The sender ID is sending to invalid recipients. |
| `POOR_DELIVERABILITY` | The sender ID is being rejected by recipients' mail servers. |
| `ESA` | The sender ID is on the MailChannels blocklist. |
| `SB01` | The envelope sender address is on the MailChannels blocklist. |
| `SB02` | The envelope sender domain is on the MailChannels blocklist. |
| `STF` | The sender ID is being rate limited. |
| `IP_VOLUME` | An IP address has suddenly increased its sending volume. |
| `IP_NDR_VOLUME` | An IP address is generating a large number of non-delivery reports. |
| `IP_ENV_SENDER` | An IP address is sending messages without a sender ID in the headers. |
| `FBL_BLOCK_550` | The sender was blocked because of feedback loop (FBL) complaints. |

## Count alerts over time

`POST /alertcount` takes the same `sender_id`, `start_date`, `end_date`, and `sub_account_filter`
fields as `POST /alerts`, plus an `interval` of `hours`, `days`, or `weeks`. The default is `days`.

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

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

import requests

response = requests.post(
    "https://api.mailchannels.net/outbound/v1/alertcount",
    headers={"X-API-KEY": os.environ["MAILCHANNELS_API_KEY"]},
    json={
        "sender_id": "examplehost|x-authuser|alice@example.com",
        "start_date": "2026-11-12T00:00:00+00:00",
        "end_date": "2026-11-19T00:00:00+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/alertcount", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.MAILCHANNELS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "sender_id": "examplehost|x-authuser|alice@example.com",
    "start_date": "2026-11-12T00:00:00+00:00",
    "end_date": "2026-11-19T00:00:00+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/alertcount');
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([
        'sender_id' => 'examplehost|x-authuser|alice@example.com',
        'start_date' => '2026-11-12T00:00:00+00:00',
        'end_date' => '2026-11-19T00:00:00+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));
```

The response maps the start of each period to the number of alerts in it. Periods start at
`start_date`, so start your range at midnight UTC if you want calendar days:

```json theme={null}
{
  "2026-11-12T00:00:00Z": 0,
  "2026-11-13T00:00:00Z": 0,
  "2026-11-14T00:00:00Z": 0,
  "2026-11-15T00:00:00Z": 0,
  "2026-11-16T00:00:00Z": 3,
  "2026-11-17T00:00:00Z": 5,
  "2026-11-18T00:00:00Z": 1
}
```

## Worked example

The [sender report example](https://docs.mailchannels.com/outbound/log-search-api/sender-profiles.md#worked-example-sender-report)
requests a sender's alerts alongside their sender profile and prints both together.

## Next steps

* [Build a sender profile](https://docs.mailchannels.com/outbound/log-search-api/sender-profiles.md) to see the traffic behind the alerts.
* [Set up monitors and alerts](https://docs.mailchannels.com/outbound/monitors-alerts.md) in the Host Console.


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