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

# AgentMail Webhook Setup Guide

> Configure AgentMail to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](https://docs.stackone.com/connectors/agentmail.md#getting-started) on the AgentMail connector page.

## How AgentMail webhooks are set up

StackOne creates and manages the AgentMail webhook subscription automatically when the account is connected, using the account's API key, and removes it when the account is disconnected. There is nothing to configure in AgentMail.

<ul>
  <li>The API key must be able to manage webhooks and read the events you enable. A full-access key (the default) covers every event.</li>
</ul>

## Available webhook events

The following AgentMail events can be enabled. Only events selected in StackOne are included in the subscription, so AgentMail does not deliver events that are not selected.

**1. Message events**

Events related to email received, sent and delivered through your inboxes.

<ul>
  <li>**Message Received** (`message.received`) — Fired when a new email is received and processed in one of your inboxes</li>
  <li>**Spam Message Received** (`message.received.spam`) — Fired when a received message is classified as spam</li>
  <li>**Blocked Message Received** (`message.received.blocked`) — Fired when a received message matches a block list entry</li>
  <li>**Unauthenticated Message Received** (`message.received.unauthenticated`) — Fired when a message is delivered with the unauthenticated label because SPF, DKIM and DMARC did not pass</li>
  <li>**Message Sent** (`message.sent`) — Fired when a message is sent from one of your inboxes</li>
  <li>**Message Delivered** (`message.delivered`) — Fired when the recipient mail server confirms delivery</li>
  <li>**Message Bounced** (`message.bounced`) — Fired when a message fails to deliver and bounces back</li>
  <li>**Message Complained** (`message.complained`) — Fired when a recipient marks your message as spam</li>
  <li>**Message Rejected** (`message.rejected`) — Fired when a message is rejected before sending</li>
  <li>**Message Opened** (`message.opened`) — Fired when a tracked message is opened for the first time. Requires open tracking</li>
</ul>

**2. Agent Armor events**

Events from Agent Armor, which scans received mail for prompt injection. Agent Armor must be turned on in AgentMail.

<ul>
  <li>**Message Security Completed** (`message.security.completed`) — Fired when Agent Armor reaches a verdict on a received message in Monitor mode</li>
  <li>**Message Security Review** (`message.security.review`) — Fired when Agent Armor in Hold mode holds a received message for review</li>
  <li>**Message Security Override** (`message.security.override`) — Fired when someone releases a message Agent Armor held</li>
</ul>

**3. Domain events**

Events related to your custom sending domains.

<ul>
  <li>**Domain Verified** (`domain.verified`) — Fired when a custom domain is verified</li>
</ul>

**4. Calendar events**

Events related to the calendars attached to your inboxes.

<ul>
  <li>**Calendar Event Created** (`calendar.event.created`) — Fired when a calendar event is created, or a date of a recurring event is edited for the first time</li>
  <li>**Calendar Event Updated** (`calendar.event.updated`) — Fired when a calendar event, or dates of a recurring event, change or are canceled</li>
  <li>**Calendar Event Deleted** (`calendar.event.deleted`) — Fired when a one-off or recurring calendar event is deleted</li>
  <li>**Calendar Event Responded** (`calendar.event.responded`) — Fired when an attendee response to an invitation changes</li>
  <li>**Calendar Event Starting** (`calendar.event.starting`) — Fired when a calendar event, or one date of a recurring event, starts</li>
  <li>**Calendar Event Ending** (`calendar.event.ending`) — Fired when a calendar event, or one date of a recurring event, ends</li>
</ul>

## Delivery format

Details of how AgentMail delivers events to StackOne.

**1. One event per request**

Each request carries a single event: `type`, `event_type`, `event_id` and the event object (for example `message`, `send` or `calendar_event`). StackOne routes each delivery to the matching event handler by `event_type`.

<ul>
  <li>Delivery is at least once. AgentMail retries failed deliveries with the same `event_id`, so StackOne uses it to deduplicate.</li>
  <li>Deliveries are signed by Svix (`svix-id`, `svix-timestamp` and `svix-signature` headers).</li>
</ul>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


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