Skip to main content

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.

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:
Example email address
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 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
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 $.
Example payload
{
  "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": "<html><body><h2>[inc-45] Disk space running low</h2></body></html>",
  "header_message_id": "1777643680-10362@my.monitoring.provider",
  "envelope": {
    "to": ["abc123xyz-f769e4dda22b@inbound.incident.io"],
    "from": "alerts@my.monitoring.provider"
  }
}
Your transform expression
return {
  title: $.subject,
  description: $.text,
  status: $.subject.indexOf('RESOLVED') > -1 ? 'resolved' : 'firing',
  deduplication_key: $.subject.split(']')[0] + ']',
  metadata: {
    from: $.from,
  },
};

​
Available fields on $

FieldDescription
toThe inbound address that received the email
fromThe sender address from the email headers
subjectThe email subject line
textPlain text body
htmlHTML body — prefer text for transforms unless you need to parse markup
header_message_idThe Message-ID header — useful as a deduplication key
envelope.fromSMTP envelope sender
envelope.toArray of SMTP envelope recipients

​
Return schema

PropertyDescription
titleThe title, or name, of the alert
statusfiring or resolved — derive from email content
descriptionAn optional long-text description, rendered alongside the title
source_urlAn optional link to the origin of the alert
deduplication_keyUsed to deduplicate alerts. Returned in the object — not configured separately
metadataAn 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 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.