How to send Email Alert

How to send email alert to EMS2.0 ¶

Summary ¶

EMS2.0 can consume alert emails from a dedicated mailbox and convert each email into an alert. This document defines the contract every email alert source must follow: where to send, what the subject must look like, and what the body may contain.

The subject is the only part of the email that EMS parses. Everything else — most importantly the body — is carried through and displayed to the operator. Getting the subject right is therefore what determines whether your alerts deduplicate, recover and route correctly.

How EMS receives email alerts ¶

EMS does not run an SMTP server and does not expose a webhook for mail. Alert emails are delivered to a normal mailbox, and EMS polls that mailbox through the Microsoft Graph API.

┌──────────────┐   send mail    ┌──────────────┐   poll unread  ┌──────────┐
│ Alert source │ ─────────────► │ EMS mailbox  │ ◄───────────── │   EMS    │
│ (script/SaaS)│                │ (Microsoft   │                │ consumer │
└──────────────┘                │  365)        │ ─── alerts ──► └──────────┘
                                └──────────────┘

Two consequences you must plan for:

• Alert delivery is not real time. Worst-case latency is one polling interval plus processing time. Do not use email for alerts that require sub-minute reaction.
• The mailbox is a queue, not an archive. After an email is converted into an alert it is marked as read and deleted. Do not send anything to this mailbox that you expect to read later, and do not use it as a distribution list for humans.

Email subject format ¶

Every alert email subject must follow this format:

[<STATUS>] [SERVICE: <ServiceName>] <Alert Identity>

Example:

[FIRING] [SERVICE: WxCCE-ECE] WX046 | den01wx046ecs01 | AOAG-SYNC-UNHEALTHY

Token 1 — [<STATUS>] (required) ¶

Must be the first token in the subject.

• FIRING and RESOLVED are the preferred values — use them for any new source. CRITICAL and CLEARED remain accepted so that sources already sending them keep working.
• Case-insensitive, but uppercase is the convention.
• Any other value (for example MAJOR, WARNING) is not recognized: the alert is raised as firing and the token stays in the alert name.
• Nothing may appear before this token. See Prefixes that break parsing.

Token 2 — [SERVICE: <ServiceName>] (optional but recommended) ¶

Identifies the source service and is shown as the Service field on the alert.

• Literal keyword SERVICE, a colon, then the service name — for example [SERVICE: WxCCE].
• Allowed characters: letters, digits, ., _, -. No [, ], no line breaks.
• Use one agreed spelling everywhere. WxCCE, wxcce and Webex CCE are three different services as far as EMS is concerned.
• If the token is absent the alert simply has no service assigned; the email is still accepted.

Token 3 — <Alert Identity> (required) ¶

Everything after the two tokens. This is the identity of the alert — EMS derives the deduplication fingerprint from it.

Two emails are treated as the same alert if and only if their identity text is identical, character for character.

Recommended identity pattern:

<tenant or platform> | <device or IP> | <component or condition>

Prefixes that break parsing ¶

Anything placed before [<STATUS>] becomes part of the alert identity and silently splits one alert into several. Make sure your sending path does not add:

• RE: / FW: from a forwarding rule or a human reply
• [EXTERNAL], [SUSPICIOUS] and similar banners added by mail security gateways
• Distribution-list tags such as [day2ops-cc]

If your emails pass through a list or a gateway that always adds a banner, tell the EMS team — the parsing rule can account for a known, fixed banner, but it must be known in advance.

Good and bad examples ¶

Email body ¶

The body is not parsed. It is carried through and displayed in the Description field of the alert, so it should read as the operator-facing detail of the event.

If your source produces a large health-check report, send a short summary of the failing components in the body and keep the full report on the source system.

What EMS does with each part of the email ¶

Deduplication and recovery ¶

The identity part of the subject is the deduplication key:

• A repeated FIRING email with the same identity does not create a new alert. It refreshes the existing one and increments its firing counter. A daily burst of five identical emails therefore produces one alert, not five.
• A RESOLVED email with the same identity moves that alert to resolved.
• A different identity is always a different alert.

If your source never sends a recovery email, say so during onboarding. EMS can close such alerts on a timeout instead (for example, resolve after three missed health-check cycles), but this has to be configured per source and is less accurate than a real RESOLVED email. Sending RESOLVED is strongly preferred.

If your source is known to flap, mention the expected pattern (how many emails, over what window). Deduplication already collapses repeats into a single alert; additional throttling can be configured when the downstream ticketing behaviour requires it.