> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.agentmail.to/llms.txt.

# Message Received

POST 

Reference: https://agentmail.to/docs/api-reference/webhooks/events/message-received

## Request

### Headers

- `svix-id` (string, required) — ID of webhook message.
- `svix-signature` (string, required) — Signature of webhook message.
- `svix-timestamp` (datetime, required) — Timestamp of webhook message.

### Payload

- `type` ("event", required)
- `event_type` (enum, required)
  - Allowed values: `message.received`, `message.received.spam`, `message.received.blocked`, `message.received.unauthenticated`
- `event_id` (string, required) — ID of event.
- `message` (Message, required)
- `thread` (ThreadItem, required)

## Types

### Message

- `inbox_id` (string, required) — The ID of the inbox.
- `thread_id` (string, required) — ID of thread.
- `message_id` (string, required) — ID of message.
- `labels` (list of string, required) — Labels of message.
- `timestamp` (datetime, required) — Time at which message was sent or drafted.
- `from` (string, required) — Address of sender. In format `username@domain.com` or `Display Name <username@domain.com>`.
- `to` (list of string, required) — Addresses of recipients. In format `username@domain.com` or `Display Name <username@domain.com>`.
- `size` (integer, required) — Size of message in bytes.
- `updated_at` (datetime, required) — Time at which message was last updated.
- `created_at` (datetime, required) — Time at which message was created.
- `reply_to` (list of string, optional) — Reply-to addresses. In format `username@domain.com` or `Display Name <username@domain.com>`.
- `cc` (list of string, optional) — Addresses of CC recipients. In format `username@domain.com` or `Display Name <username@domain.com>`.
- `bcc` (list of string, optional) — Addresses of BCC recipients. In format `username@domain.com` or `Display Name <username@domain.com>`.
- `subject` (string, optional) — Subject of message.
- `preview` (string, optional) — Text preview of message.
- `text` (string, optional) — Plain text body of message.
- `html` (string, optional) — HTML body of message.
- `extracted_text` (string, optional) — Extracted new text content.
- `extracted_html` (string, optional) — Extracted new HTML content.
- `attachments` (list of Attachment, optional) — Attachments in message.
- `in_reply_to` (string, optional) — ID of message being replied to.
- `calendar_event_id` (string, optional) — The calendar event this email's invitation was applied to: set when the email's calendar invitation, update, cancellation or attendee reply changed the inbox's calendar, a few seconds after the email arrives. For an email about one date of a recurring event, it is that date's event ID. Absent on other emails, and on invitations that were not imported. Calendar is in AgentMail Labs.
- `references` (list of string, optional) — IDs of previous messages in thread.
- `headers` (map from string to string, optional) — Headers in message.
- `agent_armor` (AgentArmorResult, optional) — Agent Armor's result for this message. Present only on messages received while Agent Armor was on for your organization. A scan starts `pending` and usually completes within seconds. `message.security.completed` is sent only for `complete` results, so a message still `pending` at `deadline_at` reads `unavailable` with no event.

### ThreadItem

- `inbox_id` (string, required) — The ID of the inbox.
- `thread_id` (string, required) — ID of thread.
- `labels` (list of string, required) — Labels of thread.
- `timestamp` (datetime, required) — Timestamp of last sent or received message.
- `senders` (list of string, required) — Senders in thread. In format `username@domain.com` or `Display Name <username@domain.com>`.
- `recipients` (list of string, required) — Recipients in thread. In format `username@domain.com` or `Display Name <username@domain.com>`.
- `last_message_id` (string, required) — ID of last message in thread.
- `message_count` (integer, required) — Number of messages in thread.
- `size` (integer, required) — Size of thread in bytes.
- `updated_at` (datetime, required) — Time at which thread was last updated.
- `created_at` (datetime, required) — Time at which thread was created.
- `received_timestamp` (datetime, optional) — Timestamp of last received message.
- `sent_timestamp` (datetime, optional) — Timestamp of last sent message.
- `subject` (string, optional) — Subject of thread.
- `preview` (string, optional) — Text preview of last message in thread.
- `attachments` (list of Attachment, optional) — Attachments in thread.

### Attachment

- `attachment_id` (string, required) — ID of attachment.
- `size` (integer, required) — Size of attachment in bytes.
- `filename` (string, optional) — Filename of attachment.
- `content_type` (string, optional) — Content type of attachment.
- `content_disposition` (enum, optional) — Content disposition of attachment.
  - Allowed values: `inline`, `attachment`
- `content_id` (string, optional) — Content ID of attachment.

### AgentArmorResult

Agent Armor's result for this message. Present only on messages received while Agent Armor was on for your organization. A scan starts `pending` and usually completes within seconds. `message.security.completed` is sent only for `complete` results, so a message still `pending` at `deadline_at` reads `unavailable` with no event.

- `status`: `pending`
  - `deadline_at` (datetime, required) — When the scan gives up. A result still pending then reads as `unavailable` with `deadline_exceeded`.
  - `started_at` (datetime, required) — When the message was received. The deadline counts from here.
- `status`: `complete`
  - `completed_at` (datetime, required) — When the scan finished.
  - `model` (string, required) — Identifies the Agent Armor release that produced the verdict. Opaque; it changes when Agent Armor is updated.
  - `reason` (string, required) — A short explanation of the verdict.
  - `verdict` (enum, required) — What the scan concluded. `clear` means Agent Armor found no threat. It is advisory, not a guarantee that the message is safe. `review` means the message may try to manipulate an agent: inspect it before an agent acts on it.
    - Allowed values: `clear`, `review`
  - `manual_override` (AgentArmorManualOverride, optional) — Present on a `review` held in hold mode that someone released.
- `status`: `unavailable`
  - `unavailable_reason` (enum, required) — Why no verdict is available.
    - Allowed values: `unsupported_dsn`, `payload_too_large`, `no_scannable_content`, `enqueue_failed`, `scorer_failed`, `contract_error`, `deadline_exceeded`

### AgentArmorManualOverride

The record of a release of a message Agent Armor held for review.

- `override_id` (string, required) — ID of the release, and the `event_id` of its `message.security.override` event.
- `actor` (AgentArmorReleaseActor, required) — Who released the message.
- `reason` (string, required) — Why it was released, as given by whoever released it.
- `original_verdict` ("review", required) — The verdict that held the message.
- `released_at` (datetime, required) — When it was released.

### AgentArmorReleaseActor

Who released the message.

- `kind`: `api_key`
  - `api_key_id` (string, required) — The API key that released it.
- `kind`: `console`