Webhook events
Learn what events Lettermint can send and how to handle them. Subscribe to the events you need when creating a webhook.
Common envelope
All webhook events share a consistent envelope:
Code
Fields:
- id: Unique identifier (UUIDv4) for the specific delivery event. Useful for idempotency.
- event: Event type.
- timestamp: ISO timestamp when the event occurred.
- data: Event-specific fields (documented per event below).
Common message data fields:
- message_id: The unique identifier for the message.
- subject: The email subject line.
- metadata: Custom metadata attached to the message (if any).
- tag: The tag assigned to categorize the message (e.g., "newsletter", "order-confirmation"). Will be
nullif no tag was assigned.
These fields apply to message.* events. Suppression events use the suppression-specific fields documented below.
Event payloads
message.created
Message accepted for processing.
Example payload:
Code
message.sent
Message sent to recipient server.
Code
message.delivered
Message successfully delivered.
Code
message.auto_replied
Recipient mail server sent an automatic reply such as an out-of-office or vacation response. Auto replies are informational and do not change the message delivery status.
Code
Fields:
auto_reply.sender: Address that sent the automatic reply, when availableauto_reply.recipient: Bounce/feedback recipient address that received the automatic replyauto_reply.subject: Subject of the automatic reply, when availableauto_reply.body.text: Plain-text automatic reply body, when availableauto_reply.body.html: HTML automatic reply body, when available
message.hard_bounced
Permanent delivery failure (e.g., user does not exist).
Code
message.soft_bounced
Temporary delivery failure (e.g., mailbox full, transient error).
Code
message.spam_complaint
Recipient reported the message as spam.
Code
message.failed
The message could not be delivered due to a terminal processing or delivery failure.
Code
When an enforced TLS policy cannot be satisfied, reason_code is enforced_tls_failed and response.status_code is 550. Temporary connection and TLS errors continue through normal retries and are reported as message.soft_bounced while retryable.
message.suppressed
Message was suppressed due to previous bounce or complaint.
Code
message.policy_rejected
Message rejected by policy (spam or content filter). This occurs when a message's spam score exceeds the configured threshold before delivery.
Code
Fields:
reason: Human-readable rejection reason (e.g., "spam content", "policy violation")score: The spam score that triggered the rejectionspam_symbols: Array of spam rule matches with name, score, options, and description
message.unsubscribed
Recipient unsubscribed from the mailing list.
Code
message.opened
Recipient opened the email. Requires open tracking to be enabled on the route.
This event is only available for routes with open tracking enabled. By default, webhooks receive only human-countable opens; machine, privacy proxy, and security scanner opens require Include machine events.
Code
Fields:
opened_at: Timestamp when the open was detectedfirst_open: Whether this is the first time this recipient opened the emaildevice_type: Device category:desktop,mobile, ortabletclient_type: Client category:browser,email_client, etc.client_name: Specific client name:Chrome,Safari,Outlook, etc.user_agent: The user agent string from the requestbot.detected: Whether the open appears to be from an automated source (bot, proxy, scanner)bot.probability: Confidence score (0-100) that this is a bot interactionbot.classification: Source classification such asgenuine,privacy_proxy,security_scanner, orgeneric_botbot.proxy_type: Known proxy family when applicable, otherwisenullbot.reason_codes: Machine-readable reasons behind the classificationbot.machine: Whether this open was classified as machine, privacy, or security activitybot.counts_for_metrics: Whether this open contributes to default engagement metrics
See Bot Detection Field Values for classification and proxy_type values, plus reason_codes guidance.
message.clicked
Recipient clicked a link in the email. Requires click tracking to be enabled on the route.
This event is only available for routes with click tracking enabled. By default, webhooks receive only human-countable clicks; machine, link preview, and security scanner clicks require Include machine events.
Code
Fields:
clicked_at: Timestamp when the click occurreddestination_url: The original destination URL that was clickedlink_index: Zero-based index of the link in the email (order of appearance)anchor_text: The visible text of the clicked linkfirst_click: Whether this is the first time this recipient clicked any link in this emaildevice_type: Device category:desktop,mobile, ortabletclient_type: Client category:browser,email_client, etc.client_name: Specific client name:Chrome,Safari,Outlook, etc.user_agent: The user agent string from the requestbot.detected: Whether the click appears to be from an automated source (security scanner, link preview bot)bot.probability: Confidence score (0-100) that this is a bot interactionbot.classification: Source classification such asgenuine,privacy_proxy,security_scanner, orgeneric_botbot.proxy_type: Known proxy family when applicable, otherwisenullbot.reason_codes: Machine-readable reasons behind the classificationbot.machine: Whether this click was classified as machine, preview, or security activitybot.counts_for_metrics: Whether this click contributes to default engagement metrics
See Bot Detection Field Values for classification and proxy_type values, plus reason_codes guidance.
Suppression events
Suppression events are emitted once per non-global suppression entry and are delivered to enabled, subscribed webhooks attached to transactional and broadcast routes affected by that entry.
Global-scope suppressions do not emit webhook events. Inbound routes do not support suppression events.
Delivery fans out according to the suppression scope:
| Suppression scope | Webhook recipients |
|---|---|
route | Webhooks attached to that route |
project | Webhooks attached to routes in that project |
team | Webhooks attached to routes in that team |
Duplicate additions do not emit another event. A removal event is emitted only when the suppression is actually deleted, so a removal that remains pending for manual review does not emit suppression.removed.
suppression.added
A suppression entry affecting the webhook's route was added. The envelope timestamp is the suppression's creation time and matches data.created_at.
Code
suppression.removed
A suppression entry affecting the webhook's route was deleted. The original suppression fields remain in the payload. The envelope timestamp is the committed removal time and matches data.removed_at.
Code
Suppression event data fields:
suppression_id: Unique identifier for the suppression entry.type: Suppressed value type:email,domain, orextension.value: The suppressed email address, domain, or extension.reason: Why the entry was created:manual,hard_bounce,spam_complaint, orunsubscribe.scope: Suppression scope:team,project, orroute.project_id: Project containing the suppression.nullfor team-scoped suppressions.route_id: Route containing the suppression.nullfor team- and project-scoped suppressions.source_message_id: Message that caused the suppression, when available; otherwisenull.created_at: Original suppression creation time.removed_at: Committed removal time. Present only onsuppression.removed.
Inbound events
message.inbound
Sent when an inbound route receives and parses an email. The event contains SMTP envelope data, parsed message headers and bodies, attachment references, spam diagnostics, and the original raw message.
This event is only available for webhooks attached to inbound routes. See Inbound Mail to create a route, or Process inbound email for handling guidance.
Example payload:
Code
Event envelope
| Field | Type | Description |
|---|---|---|
id | string | Webhook delivery ID. Lettermint reuses it when retrying the same delivery. |
event | "message.inbound" | Event type. |
timestamp | string | ISO 8601 time when Lettermint created the event. |
data | object | Parsed inbound message. |
The top-level id identifies this webhook delivery. data.message_id identifies the inbound message itself.
Message data
| Field | Type | Description |
|---|---|---|
route | string | Inbound route slug. |
message_id | string | Stable UUID for the inbound message. |
envelope | object | SMTP connection and envelope data. This is separate from visible message headers. |
from | object | Parsed visible From address. |
to | array | Parsed visible To addresses. The array can be empty. |
cc | array | Parsed visible Cc addresses. The array can be empty. |
recipient | string | null | Primary SMTP envelope recipient. Use this field for application routing. |
subaddress | string | null | Plus tag from recipient, without the +. |
reply_to | string | null | Parsed Reply-To address. |
subject | string | null | Parsed message subject. |
date | string | ISO 8601 time when Lettermint received the message. |
body.text | string | null | Plain-text body. |
body.html | string | null | HTML body. Sanitize it before rendering. |
tag | string | null | Valid tag parsed from X-LM-Tag or X-Tag. |
headers | array | Parsed non-standard headers as name and value pairs. Standard address, subject, and date headers are represented by dedicated fields. |
authentication_results | object | Structured DKIM, DMARC, and SPF results produced during inbound scanning. |
attachments | array | Attachment objects in exactly one of the delivery shapes below. The array can be empty. |
raw | object | Always-present signed reference to the original .eml message. |
is_spam | boolean | Whether the configured route threshold classified the message as spam. |
spam_score | number | null | Score produced by inbound spam scanning. |
spam_symbols | array | null | Diagnostic scanner symbols. Use authentication_results for stable authentication decisions. |
Each address in from, to, and cc contains email, nullable name, and nullable subaddress. Envelope fields remote_ip, remote_hostname, helo, and mail_from are strings or null when the SMTP session did not provide a usable value.
authentication_results always contains authserv_id, an RFC-style header string, and structured dkim, dmarc, and spf objects. Each method has a result. Related domain, selector, and policy fields can be null. A result can be pass, fail, softfail, neutral, temperror, permerror, none, or unknown.
Attachment delivery shapes
Every attachment contains nullable filename, a content_type string, nullable integer size, and nullable content_id. The remaining fields depend on the route's Attachments setting:
| Mode | Present fields | Absent fields |
|---|---|---|
| Inline | content with Base64-encoded bytes | url, expires_at |
| Signed URL | url, expires_at | content |
The raw object always contains url and expires_at. Attachment and raw-message signed URLs expire after 28 days. See Attachments and raw email for configuration and secure processing guidance.
Verify the webhook signature before trusting these fields. See Signed webhooks for complete examples.
Test events
webhook.test
Special event that can be triggered from the Dashboard for connectivity testing.
Code
Next Steps
- Signed Webhooks: Verify the authenticity of webhook payloads.
- Quick introduction: Learn about all the events Lettermint sends.