Event types

Every event type Supermail emits, its payload, and the shared value types they carry.

Every event shares one envelope; type selects which payload field is present. Types are dotted noun.past_tense strings. Skip any type you do not recognize — the set is additive.

`type`	Payload field	Meaning
`email.received`	`email_received`	A message newly appeared in the account's view
`email.updated`	`email_updated`	A provider-side change to an existing message
`email.deleted`	`email_deleted`	A message was removed/expunged
`email.placement_upserted`	`email_placement_upserted`	A message gained or changed one mailbox occurrence
`email.placement_removed`	`email_placement_removed`	A message lost one mailbox occurrence
`email.sent`	`email_sent`	A durable submission reached the provider
`email.send_failed`	`email_send_failed`	A durable submission ended in permanent failure
`mailbox.changed`	`mailbox_changed`	A folder was created, removed, renamed, or updated
`label.changed`	`label_changed`	A label was created, updated, or removed through Supermail
`sync.started`	`sync_started`	A sync began
`sync.progress`	`sync_progress`	Chunk-level progress during a (back)fill
`sync.completed`	`sync_completed`	A sync finished
`sync.failed`	`sync_failed`	A sync ended in failure

Message events

Message events are thin change notifications. They identify the message and its mailbox occurrences and carry no addresses, dates, flags, attachments, or content references; mail content and metadata are replicated to authorized consumers through the content lane.

`email.received`

Field	Type	Notes
`provider_id`	`ProviderId`	Which message
`placements`	`MailboxOccurrence`[]	Mailboxes it appeared in
`thread_id`	string, optional	The provider's own conversation: Gmail `threadId`, Outlook `conversationId`. Opaque, scoped to the account and fixed for the message's lifetime; absent when the provider has none (IMAP)

Messages with the same thread_id in one account belong to one provider conversation. There are no thread-level writes: act on each message.

The native Rust event DTO has one JSON wire representation, used for retained event reads and signed webhook delivery.

Example event (JSON)

{
  "id": "event_3Nq7...",
  "seq": "128",
  "type": "email.received",
  "account_id": "account_01H9X...",
  "created": "2026-07-12T09:15:00+00:00",
  "idempotency_key": "INBOX:12345:98",
  "provenance": {
    "channel_id": "channel_01H...",
    "provider": { "mailbox": "INBOX", "uidvalidity": "98", "uid": "12345" },
    "cause": "sync.managed"
  },
  "email_received": {
    "provider_id": {
      "object_id": "...",
      "rfc_message_id": "<abc@example.com>"
    },
    "placements": [{ "mailbox_id": "...", "occurrence_id": "..." }],
    "thread_id": "18cafe00..."
  }
}

`email.updated`

Field	Type	Notes
`provider_id`	`ProviderId`	Which message
`placements`	`MailboxOccurrence`[]	Its current mailbox occurrences
`changes`	string[]	What changed, e.g. `["flags"]`

`email.deleted`

Field	Type	Notes
`provider_id`	`ProviderId`	Which message
`placements`	`MailboxOccurrence`[]	Occurrences it was removed from

`email.placement_upserted`

Field	Type	Notes
`provider_id`	`ProviderId`	Which message
`mailbox_id`	string	The mailbox holding the occurrence
`occurrence_id`	string	The upserted occurrence

`email.placement_removed`

Field	Type	Notes
`provider_id`	`ProviderId`	Which message
`mailbox_id`	string	The mailbox that held the occurrence
`occurrence_id`	string	The removed occurrence

`email.sent`

Field	Type	Notes
`submission_id`	string	The terminal `sub_…` submission
`message_id`	string	Its RFC 5322 `Message-ID`
`operation_id`	string (optional)	The owning operation

`email.send_failed`

Field	Type	Notes
`submission_id`	string	The terminal `sub_…` submission
`failure`	`Failure`	Stable failure code and recommended action
`operation_id`	string (optional)	The owning operation

Mailbox events

`mailbox.changed`

Field	Type	Notes
`mailbox_id`	string	The affected folder/label
`kind`	`ChangeKind`	`CHANGE_KIND_CREATED`, `CHANGE_KIND_REMOVED`, `CHANGE_KIND_RENAMED`, or `CHANGE_KIND_UPDATED`
`previous_mailbox_id`	string (optional)	The prior id, when the change replaced it

Read the folder's current name, role and parent with Folders/list.

`label.changed`

Field	Type	Notes
`label_id`	string	The provider label: a Gmail label id, an Outlook category name or an IMAP keyword
`kind`	`ChangeKind`	`CHANGE_KIND_CREATED`, `CHANGE_KIND_UPDATED` (renamed or recolored; the id is kept), or `CHANGE_KIND_REMOVED`

Emitted when a Labels/create, Labels/update or Labels/delete operation is confirmed by the provider. Labels changed in another client emit no event; read the current catalog with Labels/list.

Sync events

These carry no provider coordinates.

`sync.started`

Field	Type	Notes
`job_id`	string	The synchronization job
`selection`	`SyncSelection`	Exactly one of `changes`, `history`, or `snapshot`, as requested
`operation_id`	string (optional)	The owning operation

`sync.progress`

Field	Type	Notes
`done`	int64	Items processed so far
`total`	int64 (optional)	Total, when known
`chunk`	int64	The current chunk index
`job_id`	string	The synchronization job
`operation_id`	string (optional)	The owning operation

`sync.completed`

Field	Type	Notes
`count`	int64	Items observed
`job_id`	string	The synchronization job
`operation_id`	string	The owning operation, also reported by `operation.succeeded`

`sync.failed`

Field	Type	Notes
`job_id`	string	The synchronization job
`failure`	`Failure`	Stable failure code and recommended action; `retry_after` is never set
`operation_id`	string (optional)	The owning operation

Value types

`ProviderId`

Opaque provider message coordinates — match, never parse.

Field	Type
`object_id`	string
`rfc_message_id`	string (optional)

`MailboxOccurrence`

One occurrence of a message in a mailbox.

Field	Type
`mailbox_id`	string
`occurrence_id`	string

Content references

Events carry no content_ref. Gateway exposes no public endpoint that resolves event payloads to bytes; raw content is served only through the content lane to authorized DUCS consumers.

On this page