Message Events
These events track the delivery lifecycle of emails you send through Lettr.message.injection
Triggered when an email is accepted by Lettr and queued for delivery. This is the first event in any email’s lifecycle.message.delivery
Triggered when an email is successfully delivered to the recipient’s mail server. This is the most reliable indicator that the email reached its destination.A delivery event means the recipient’s mail server accepted the email. It does not guarantee the email reached the inbox — it could be filtered to spam or quarantined by the recipient’s email provider.
message.bounce
Triggered when an email cannot be delivered. Bounces can be hard (permanent failure, such as a non-existent address) or soft (temporary issue, such as a full mailbox).message.delay
Triggered when email delivery is temporarily delayed. Lettr will continue retrying delivery automatically. Delays are common with large mail providers that throttle incoming connections.message.out_of_band
Triggered when an out-of-band bounce occurs. These arrive after the initial delivery appeared successful — the receiving server accepted the message initially, then later determined it could not be delivered and sent a separate bounce notification.message.spam_complaint
Triggered when a recipient marks an email as spam. This is a serious signal that should trigger immediate suppression.message.policy_rejection
Triggered when an email is rejected due to a policy rule before delivery was attempted. This could be due to content filtering, rate limits, or a configuration issue.Engagement Events
These events indicate that the recipient interacted with your email. Engagement events require open and/or click tracking to be enabled.The engagement event category contains a known typo in the event names:
engagament (missing an ‘e’). This is intentional for backward compatibility and must be used exactly as shown.engagament.open
Triggered when a recipient opens an email. Open tracking works by embedding a small invisible image in the email. Some email clients block images by default or prefetch them automatically, so open rates are an approximation rather than an exact count.engagament.initial_open
Triggered on the first open of an email by a recipient. Subsequent opens of the same email generateengagament.open events instead.
engagament.click
Triggered when a recipient clicks a link in an email. Requires click tracking to be enabled. Click data is generally more reliable than open data because it requires deliberate user action.engagament.amp_open
Triggered when a recipient opens an email delivered in AMP format.engagament.amp_initial_open
Triggered on the first open of an AMP email by a recipient.engagament.amp_click
Triggered when a recipient clicks a link within an AMP email.Generation Events
These events occur when there is a problem generating (assembling and preparing) a message for delivery.generation.generation_failure
Triggered when something goes wrong while preparing the message for delivery. This is typically an infrastructure-level issue rather than something caused by your email content.generation.generation_rejection
Triggered when a message is blocked during the generation phase — the point where the email is assembled and prepared for sending.Unsubscribe Events
These events track when recipients opt out of receiving your emails.unsubscribe.list_unsubscribe
Triggered when a recipient unsubscribes via the List-Unsubscribe header, a one-click unsubscribe mechanism built into email standards.unsubscribe.link_unsubscribe
Triggered when a recipient unsubscribes by clicking an unsubscribe link in the email body.Relay Events
These events are triggered by inbound email processing on your configured inbound domains.relay.relay_injection
Triggered when an inbound email is received and queued for processing.relay.relay_delivery
Triggered when an inbound email is successfully delivered to your configured endpoint.relay.relay_rejection
Triggered when an inbound email is rejected.relay.relay_tempfail
Triggered when delivery of an inbound email to your endpoint temporarily fails. Lettr will retry automatically.relay.relay_permfail
Triggered when delivery of an inbound email to your endpoint permanently fails after all retry attempts are exhausted.Complete Event Type Reference
| Category | Event Type | Label |
|---|---|---|
| Message | message.injection | Injection |
| Message | message.delivery | Delivery |
| Message | message.bounce | Bounce |
| Message | message.delay | Delay |
| Message | message.out_of_band | Out of Band |
| Message | message.spam_complaint | Spam Complaint |
| Message | message.policy_rejection | Policy Rejection |
| Engagement | engagament.open | Open |
| Engagement | engagament.initial_open | Initial Open |
| Engagement | engagament.click | Click |
| Engagement | engagament.amp_open | AMP Open |
| Engagement | engagament.amp_initial_open | AMP Initial Open |
| Engagement | engagament.amp_click | AMP Click |
| Generation | generation.generation_failure | Generation Failure |
| Generation | generation.generation_rejection | Generation Rejection |
| Unsubscribe | unsubscribe.list_unsubscribe | List Unsubscribe |
| Unsubscribe | unsubscribe.link_unsubscribe | Link Unsubscribe |
| Relay | relay.relay_injection | Relay Injection |
| Relay | relay.relay_delivery | Relay Delivery |
| Relay | relay.relay_rejection | Relay Rejection |
| Relay | relay.relay_tempfail | Relay Temporary Failure |
| Relay | relay.relay_permfail | Relay Permanent Failure |