Events

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)

Contact events

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 workspace 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

Event data types

The data object is JSON. JSON does not have a native date type, so date values should be sent as ISO 8601 strings. MailGlyph infers custom field types from received values when those fields are used in builders such as segments and workflow conditions:

Type	Example
String	`"premium"`
Number	`99`
Boolean	`true`
Date	`"2026-06-15T10:30:00Z"`

Use UTC date-time strings with a Z timezone suffix for date fields:

{
  "event": "subscription.started",
  "email": "[email protected]",
  "data": {
    "plan": "premium",
    "subscription_started_date": "2026-06-15T10:30:00Z"
  }
}

In PHP, you can produce this value with gmdate('Y-m-d\TH:i:s\Z').

If the same custom data key receives mixed types across events or contacts, MailGlyph may treat that field as a string.

Tracked events are queryable via:

List events (GET /events) with optional eventName filter and limit
List event names (GET /events/names) for unique names in your workspace

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.

Documentation

SDKs

API Reference

Event sources

System events reference

Email events

Contact events

Segment membership events

How event ingestion works

Event payload model

Event data types

How events are used in MailGlyph

Workflow triggers

Segment conditions

Webhook forwarding

Authentication model

​Event sources

​System events reference

​Email events

​Contact events

​Segment membership events

​How event ingestion works

​Event payload model

​Event data types

​How events are used in MailGlyph

​Workflow triggers

​Segment conditions

​Webhook forwarding

​Authentication model

​Related pages

Event sources

System events reference

Email events

Contact events

Segment membership events

How event ingestion works

Event payload model

Event data types

How events are used in MailGlyph

Workflow triggers

Segment conditions

Webhook forwarding

Authentication model

Related pages