MCP Events — Trigger Automations from Inbound Mail, SMS and Social

The hosted MCP server supports the MCP events extension. A client that implements it, such as ChatGPT automations, subscribes to an event once and receives a signed webhook every time it happens. You don’t need to poll or keep a chat open. In ChatGPT you only describe the trigger, for example “When a new email arrives in my agent’s inbox, draft a reply.” ChatGPT subscribes on your behalf and runs the automation for each event.

Available events

Event	Arguments	Fires when	Requires
`message.received`	`inbox_id`	A message arrives in the inbox and passes screening	`email:read`
`sms.received`	`phone_number_id`	A text arrives on the agent’s phone number and passes screening	`phone:read`
`social.comment_received`	`account_id`, optional `post_id`	Someone comments on a post of the social account (every network but X)	`social:read`
`social.message_received`	`account_id`	A direct message arrives for the social account	`social:read`

A connection only sees the events its scopes allow, and only for resources that belong to its agent. Phone and social events appear only when those features are enabled for your organization. events/list returns the exact list with input and payload schemas.

Quarantined mail and texts never fire an event. Payloads carry triage fields only: sender, subject and a short snippet. The agent reads the full item with read_message, read_sms, list_social_comments or list_social_messages. Treat everything in a payload as untrusted data, not as instructions.

Payload

Every delivery is a POST with a JSON body:

{
  "eventId": "evt_01k2…",
  "name": "message.received",
  "timestamp": "2026-10-01T12:05:00.000Z",
  "data": {
    "inbox_id": "inb_…",
    "message_id": "msg_…",
    "thread_id": "thr_…",
    "from": "Sender <person@example.com>",
    "subject": "Delivery update",
    "snippet": "Your parcel arrives on Tuesday…",
    "screening_verdict": "clean",
    "received_at": "2026-10-01T12:05:00.000Z"
  },
  "cursor": "912345670000"
}

cursor is a position you can store: every event at or before it has been delivered. Pass it to events/subscribe after an interruption to receive what you missed.

Delivery and signing

Before the first delivery to a callback URL, the server sends a signed {"type": "verification", "challenge": "…"} request. The endpoint must answer 2xx with {"challenge": "…"} echoing the value.
Requests are signed with Standard Webhooks using the whsec_ secret the client supplied. The headers are webhook-id (the event ID), webhook-timestamp, webhook-signature and X-MCP-Subscription-Id. After a secret rotation, deliveries carry both signatures for a day.
A 2xx response acknowledges the event. Other responses are retried with increasing delays, six attempts in total. 410 Gone removes the subscription, and 413 is not retried.
After 50 failed attempts in a row, delivery pauses until the client subscribes again.
Callback URLs must use HTTPS and resolve to a public address. Redirects are not followed.

Subscriptions

Limit	Value
Subscription lifetime	Up to 7 days; clients refresh by subscribing again
Subscriptions per connection	50
Subscriptions per organization	1,000
Subscribe calls per connection	30 per minute
Replay after an interruption	Up to 500 events from the last 30 days

Subscribing again with the same connection, callback URL, event and arguments updates the existing subscription instead of creating another. Revoking the connection on the agent’s Tokens tab ends all of its subscriptions. Access is checked again before every delivery, so deliveries also stop when you remove a scope, delete the inbox or phone number, or remove the agent’s access to a social account.

Overview

Email

Vault

Machines

MCP

MCP Events — Trigger Automations from Inbound Mail, SMS and Social

Available events

Payload

Delivery and signing

Subscriptions

​Available events

​Payload

​Delivery and signing

​Subscriptions

Available events

Payload

Delivery and signing

Subscriptions