Events are the core signal system in MailGlyph. They let you describe what happened for a contact (for example user.signup, purchase, or email.bounce) and use that signal to automate actions.
Event sources
MailGlyph supports two event sources:
| Source | How events are created | Example events |
|---|
| Custom events | You send events with /v1/track | user.signup, order.completed, purchase |
| Internal events | MailGlyph emits events automatically from platform activity | email.sent, email.delivery, email.open, email.click, email.bounce, email.complaint, email.received, contact.subscribed, contact.unsubscribed, segment.<name>.entry, segment.<name>.exit |
Internal events are system-generated and cannot be manually tracked through /v1/track.
System events reference
Use this table as the canonical list of built-in events you can trigger workflows with.
Email events
| Event | When it is triggered | Why you would use it |
|---|
email.sent | After MailGlyph successfully hands off an outbound email to the delivery provider and stores it as sent | Start post-send automations or audit outbound delivery attempts |
email.delivery | When MailGlyph receives a delivery confirmation for an outbound email | Measure delivery reliability and trigger delivered-based flows |
email.open | On open notifications; includes first-open and repeated open metadata | Engagement automation (for example, follow-ups for engaged contacts) |
email.click | On click notifications; includes clicked URL, first-click, and repeated click metadata | Link-level engagement and intent-based automation |
email.bounce | When MailGlyph receives a bounce notification. Permanent bounces include bouncedAt; transient bounces are tracked for visibility and marked transientBounce: true | Protect sender reputation, react to invalid addresses, and monitor soft-bounce patterns |
email.complaint | When MailGlyph receives a spam complaint notification | Immediate suppression/escalation workflows and deliverability protection |
email.received | When inbound email is received on a verified domain with inbound enabled | Build inbound automations (support routing, reply workflows, intake pipelines) |
| Event | When it is triggered | Why you would use it |
|---|
contact.subscribed | When a contact’s subscribed flag changes to true (API, dashboard/public subscribe flows, bulk operations) | Re-entry onboarding, preference-sync, and consent lifecycle tracking |
contact.unsubscribed | When a contact’s subscribed flag changes to false (API, dashboard/public unsubscribe flows, bulk operations, bounce/complaint auto-unsubscribe) | Compliance workflows, unsubscribe list sync, and win-back follow-up actions |
Segment membership events
| Event | When it is triggered | Why you would use it |
|---|
segment.<name>.entry | When a contact enters a segment that has membership tracking enabled | Trigger automations at the moment a contact qualifies for an audience |
segment.<name>.exit | When a contact leaves a segment that has membership tracking enabled | Trigger offboarding/re-engagement when a contact no longer matches criteria |
Segment events use a slugified segment name, for example segment.vip-users.entry.
How event ingestion works
When you call /v1/track, MailGlyph:
- Validates the incoming event payload (
email and event are required)
- Creates or updates the matching contact
- Stores the event with its
name, optional data, and timestamp
- Makes the event available to workflows, segments, and event query endpoints
If the project is at its active contact limit, MailGlyph can still create the recipient as a pending contact so event flow continues.
Event payload model
Custom events accept:
| Field | Required | Description |
|---|
email | Yes | Contact email address |
event | Yes | Event name |
subscribed | No | Contact subscription state (defaults to true) |
data | No | Arbitrary event metadata object |
- List events (
GET /events) with optional eventName filter and limit
- List event names (
GET /events/names) for unique names in your project
For per-event payload fields (for example bounceType, isFirstOpen, link, reason), see Webhooks.
How events are used in MailGlyph
Workflow triggers
Workflows start when a trigger event is received. You can trigger on custom events (from /v1/track) or internal events (like email.bounce or contact.unsubscribed). See Workflows.
You can reference event data in workflow steps using event variables (for example {{event.subject}} or {{event.from}}).
Segment conditions
Dynamic segments can filter on event-based conditions, including:
- Custom events (for example
event.signed_up, event.purchased)
- Email activity events (for example opens, clicks, bounces)
Webhook forwarding
A workflow can forward any trigger event to your own API with a Webhook step. This is how MailGlyph provides real-time outbound event delivery for both internal and custom events. See Webhooks.
Authentication model
- Use the public API key for
/v1/track
- Use the secret API key for listing/querying events (
/events, /events/names)
See API Keys for key management details.
Related pages
