Prerequisites
The connector should already be set up, with a Connector Profile and a Linked Account. See 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.
- The API key must be able to manage webhooks and read the events you enable. A full-access key (the default) covers every event.
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.
Message events
Events related to email received, sent and delivered through your inboxes.
- Message Received (
message.received) — Fired when a new email is received and processed in one of your inboxes - Spam Message Received (
message.received.spam) — Fired when a received message is classified as spam - Blocked Message Received (
message.received.blocked) — Fired when a received message matches a block list entry - Unauthenticated Message Received (
message.received.unauthenticated) — Fired when a message is delivered with the unauthenticated label because SPF, DKIM and DMARC did not pass - Message Sent (
message.sent) — Fired when a message is sent from one of your inboxes - Message Delivered (
message.delivered) — Fired when the recipient mail server confirms delivery - Message Bounced (
message.bounced) — Fired when a message fails to deliver and bounces back - Message Complained (
message.complained) — Fired when a recipient marks your message as spam - Message Rejected (
message.rejected) — Fired when a message is rejected before sending - Message Opened (
message.opened) — Fired when a tracked message is opened for the first time. Requires open tracking
Agent Armor events
Events from Agent Armor, which scans received mail for prompt injection. Agent Armor must be turned on in AgentMail.
- Message Security Completed (
message.security.completed) — Fired when Agent Armor reaches a verdict on a received message in Monitor mode - Message Security Review (
message.security.review) — Fired when Agent Armor in Hold mode holds a received message for review - Message Security Override (
message.security.override) — Fired when someone releases a message Agent Armor held
Domain events
Events related to your custom sending domains.
- Domain Verified (
domain.verified) — Fired when a custom domain is verified
Calendar events
Events related to the calendars attached to your inboxes.
- 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 - Calendar Event Updated (
calendar.event.updated) — Fired when a calendar event, or dates of a recurring event, change or are canceled - Calendar Event Deleted (
calendar.event.deleted) — Fired when a one-off or recurring calendar event is deleted - Calendar Event Responded (
calendar.event.responded) — Fired when an attendee response to an invitation changes - Calendar Event Starting (
calendar.event.starting) — Fired when a calendar event, or one date of a recurring event, starts - Calendar Event Ending (
calendar.event.ending) — Fired when a calendar event, or one date of a recurring event, ends
Delivery format
Details of how AgentMail delivers events to StackOne.
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.
- Delivery is at least once. AgentMail retries failed deliveries with the same
event_id, so StackOne uses it to deduplicate. - Deliveries are signed by Svix (
svix-id,svix-timestampandsvix-signatureheaders).