> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Email alert sources
> Turn inbound emails into structured alerts, with optional JavaScript to extract the fields you need.
Use email alert sources when a monitoring tool, script, or workflow can send email but doesn't support webhooks. Emails sent to the source's unique address can be used to create alerts in incident.io.
## Creating an email alert source
When you create an email source, incident.io generates a unique inbound address like the one below:
```text Example email address theme={null}
abc123xyz-f769e4dda22b@inbound.incident.io
```
Configure your monitoring tool, ticketing system, or forwarding rule to send to this address.
Email sources are useful for:
* Synthetic monitors, cron jobs, or legacy scripts that only emit email
* Customer support or internal escalations where critical emails should trigger alerts
## Default behavior
Without advanced email parsing, email sources work in standard mode:
* The subject becomes the alert title and the body becomes the description
* Each email creates a new alert (no deduplication)
* Alerts stay in `Firing` indefinitely and need manually resolving
In the default mode emails can't resolve themselves, so we recommend enabling [auto-resolve](/on-call/alert-sources#auto-resolve-alerts) on email sources, or using advanced email parsing to derive status from the email content.
## Advanced email parsing
Enable **Advanced email parsing** in the alert source's connection manager to write a transform expression — JavaScript that extracts structured data from incoming emails. Use this when you want to:
* Deduplicate alerts so the same issue doesn't create multiple alerts
* Mark alerts as resolved based on subject or body patterns
* Pull team, severity, or service information into [alert attributes](/on-call/alert-attributes)
The transform expression is ES5-compatible JavaScript that returns an object matching incident.io's standard alert schema, having extracted fields from the inbound email `$`.
```json Example payload theme={null}
{
"id": "01KQHX3X8676X6B4WHJKCBM0PV",
"to": "abc123xyz-f769e4dda22b@inbound.incident.io",
"from": "alerts@my.monitoring.provider",
"subject": "[inc-45] Disk space running low on logging server",
"text": "Automated alert triggered by monitoring system. Severity: warning. Status: triggered. Timestamp: 2026-05-01T13:54:40Z",
"html": "[inc-45] Disk space running low
",
"header_message_id": "1777643680-10362@my.monitoring.provider",
"envelope": {
"to": ["abc123xyz-f769e4dda22b@inbound.incident.io"],
"from": "alerts@my.monitoring.provider"
}
}
```
```javascript Your transform expression theme={null}
return {
title: $.subject,
description: $.text,
status: $.subject.indexOf('RESOLVED') > -1 ? 'resolved' : 'firing',
deduplication_key: $.subject.split(']')[0] + ']',
metadata: {
from: $.from,
},
};
```
### Available fields on `$`
| Field | Description |
| ------------------- | ------------------------------------------------------------------------ |
| `to` | The inbound address that received the email |
| `from` | The sender address from the email headers |
| `subject` | The email subject line |
| `text` | Plain text body |
| `html` | HTML body — prefer `text` for transforms unless you need to parse markup |
| `header_message_id` | The `Message-ID` header — useful as a deduplication key |
| `envelope.from` | SMTP envelope sender |
| `envelope.to` | Array of SMTP envelope recipients |
### Return schema
| Property | Description |
| ------------------- | ------------------------------------------------------------------------------ |
| `title` | The title, or name, of the alert |
| `status` | `firing` or `resolved` — derive from email content |
| `description` | An optional long-text description, rendered alongside the title |
| `source_url` | An optional link to the origin of the alert |
| `deduplication_key` | Used to deduplicate alerts. Returned in the object — not configured separately |
| `metadata` | An unstructured object for attributes like team, service, or severity |
Expressions that take longer than 25 milliseconds to execute will result in a default alert being created. Plain
JavaScript expressions normally execute in well under a millisecond.
## FAQs
If we hit an error running the transform expression, we'll create a default alert with the whole payload accessible on a `source_payload` property when inspecting the alert.
Emails don't have a built-in concept of resolution. Either derive status from the subject or body in your transform
expression (e.g. resolve when the subject starts with `[RESOLVED]`), or enable
[auto-resolve](/on-call/alert-sources#auto-resolve-alerts) on the source so alerts time out after a set duration.
We'll use the message ID from the email headers. The `header_message_id` is a stable per-email identifier; for
repeated alerts about the same underlying issue we'd recommend using transform expressions to derive a key from the
subject or a structured field in the body.
Yes — `$.html` is available, but reliably parsing HTML inside a 25ms transform is hard. Most monitoring tools include a plain text alternative in `$.text`. Prefer that when possible.