---
title: "Mail Event"
method: POST
path: "/mail-event"
tags: ["Webhooks"]
---

# Mail Event

`POST /mail-event` (webhook)

Fired when a mail event occurs on a mailbox with an active mail-event subscription. Events include `message.received`, `message.sent`, `message.forwarded`, `message.delivered`, `message.bounced`, and `message.failed`. This is fire-and-forget: the response status is logged but does not affect mail processing.

If your organization has a signing key, every webhook includes three headers:
- `X-Inkbox-Request-ID` — UUID for deduplication.
- `X-Inkbox-Timestamp` — Unix timestamp in seconds.
- `X-Inkbox-Signature` — `sha256={HMAC-SHA256 hex digest}` over `{request_id}.{timestamp}.{raw_body}`.

## Payload

- MailWebhookPayload
  - `id` string, required — Stable per-event id (evt_...); idempotency key, stable across replays.
  - `event_type` 'message.received' | 'message.sent' | 'message.forwarded' | 'message.delivered' | 'message.bounced' | 'message.failed', required
  - `timestamp` string, date-time, required — ISO 8601 timestamp of when the event occurred.
  - `data` MailWebhookData, required
    - `message` MailWebhookMessageData, required
      - `id` string, uuid, required
      - `mailbox_id` string, uuid, required
      - `thread_id` string, uuid, nullable, required
      - `message_id` string, nullable, required
      - `from_address` string, required
      - `to_addresses` string[], required
      - `cc_addresses` string[], nullable, required
      - `bcc_addresses` string[], nullable
      - `subject` string, nullable, required
      - `snippet` string, nullable, required
      - `email_address` string, nullable
      - `body` string, nullable
      - `body_state` 'complete' | 'truncated' | 'unavailable'
      - `body_truncated` boolean, nullable
      - `body_total_chars` integer, nullable
      - `body_included_chars` integer, nullable
      - `direction` 'inbound' | 'outbound', required
      - `status` 'queued' | 'sent' | 'delivered' | 'bounced' | 'failed' | 'received' | 'deleted', required
      - `has_attachments` boolean, required
      - `created_at` string, date-time, nullable, required
    - `contacts` WebhookMailContact[]
      - `bucket` 'from' | 'to' | 'cc' | 'bcc', required
      - `address` string, required
      - `id` string, uuid, required
      - `name` string, nullable, required
      - `memories` string[]
    - `agent_identities` WebhookMailAgentIdentity[]
      - `bucket` 'from' | 'to' | 'cc' | 'bcc', required
      - `address` string, required
      - `id` string, uuid, required
      - `agent_handle` string, required
      - `display_name` string, nullable

## Acknowledgement `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/inkbox/apis/inkbox-api.md) · [All operations](https://skmtc.dev/inkbox/apis/inkbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inkbox/inkbox-api/revisions/31f357e7e6f8/schema)