> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailglyph.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Understand how MailGlyph ingests, stores, and uses events across contacts, workflows, segments, and webhooks.

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`](https://docs.mailglyph.com/api-reference/public-api/trackEvent) | `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` |

> [!NOTE]
>
> 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 |

> [!NOTE]
>
> Segment events use a slugified segment name, for example `segment.vip-users.entry`.

## How event ingestion works

When you call [`/v1/track`](https://docs.mailglyph.com/api-reference/public-api/trackEvent), MailGlyph:

1. Validates the incoming event payload (`email` and `event` are required)
2. Creates or updates the matching [contact](https://docs.mailglyph.com/concepts/contacts.md)
3. Stores the event with its `name`, optional `data`, and timestamp
4. 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](https://docs.mailglyph.com/concepts/contacts.md#pending-contacts) 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:

```json theme={null}
{
  "event": "subscription.started",
  "email": "user@example.com",
  "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')`.

> [!NOTE]
>
> 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](https://docs.mailglyph.com/api-reference/events/listEvents.md) (`GET /events`) with optional `eventName` filter and `limit`
* [List event names](https://docs.mailglyph.com/api-reference/events/listEventNames.md) (`GET /events/names`) for unique names in your workspace

For per-event payload fields (for example `bounceType`, `isFirstOpen`, `link`, `reason`), see [Webhooks](https://docs.mailglyph.com/guides/webhooks.md#event-data-by-type).

## 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](https://docs.mailglyph.com/concepts/workflows.md).

You can reference event data in workflow steps using `event` variables (for example `{{event.subject}}` or `{{event.from}}`).

### Segment conditions

[Dynamic segments](https://docs.mailglyph.com/concepts/segments.md) 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](https://docs.mailglyph.com/guides/webhooks.md).

## Authentication model

* Use the **public API key** for [`/v1/track`](https://docs.mailglyph.com/api-reference/public-api/trackEvent)
* Use the **secret API key** for listing/querying events (`/events`, `/events/names`)

See [API Keys](https://docs.mailglyph.com/guides/api-keys.md) for key management details.

## Related pages

* [Workflows](https://docs.mailglyph.com/concepts/workflows.md)
* [Segments](https://docs.mailglyph.com/concepts/segments.md)
* [Webhooks](https://docs.mailglyph.com/guides/webhooks.md)
* [Tracking](https://docs.mailglyph.com/guides/tracking.md)
* [Track event API](https://docs.mailglyph.com/api-reference/public-api/trackEvent.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.