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

# MCP Events

> Wake ChatGPT tasks and other MCP agents when something happens in Sequenzy, such as a reply, a bounce or a new subscriber

MCP Events let an AI agent react to Sequenzy as things happen instead of
checking on a schedule. Tell a ChatGPT task what to watch and what to do, and
Sequenzy calls it back each time a matching event happens.

For example, in a ChatGPT task connected to Sequenzy, ask:

> When someone replies to a campaign, draft a reply in my CRM.

ChatGPT subscribes to `email.replied`. Each reply wakes the task with who
replied, the subject and a link to the conversation, and the task drafts the
reply in your CRM.

MCP Events are available on the hosted MCP server
(`https://api.sequenzy.com/v1/mcp` and the ChatGPT connector
`https://api.sequenzy.com/v1/mcp/openai`). The local `npx @sequenzy/mcp`
server does not offer events. To connect, see
[Connect AI assistants](./mcp).

## Supported events

| Event | Fires when | Optional filters | Permission needed |
| - | - | - | - |
| `email.replied` | A subscriber replies to an email you sent | `campaign_id`, `sequence_id` | `conversations:read` |
| `email.bounced` | An email you sent bounces | `campaign_id`, `sequence_id` | `analytics:read` |
| `email.complained` | A recipient marks an email as spam | `campaign_id`, `sequence_id` | `analytics:read` |
| `poll.answered` | A recipient answers a poll in an email | `campaign_id`, `sequence_id` | `analytics:read` |
| `subscriber.created` | A subscriber is added, from any source | `list_id`, `tag` | `subscribers:read` |
| `subscriber.unsubscribed` | A subscriber unsubscribes | `tag` | `subscribers:read` |
| `campaign.sent` | A campaign finishes sending | `campaign_id` | `campaigns:read` |
| `sequence.finished` | A subscriber reaches the end of a sequence | `sequence_id` | `sequences:read` |
| `subscriber_import.completed` | A subscriber import finishes | none | `subscribers:read` |

Your agent only sees the events its connection has permission to read in the
selected workspace. See [MCP permissions](./mcp-permissions) to widen a
connection without reconnecting. Connections that act with the marketer role do not
receive events from transactional emails, matching what they can read through
the API.

Filters are optional. When you give more than one, an event must match all of
them. `tag` matches the subscriber's tags when the event is processed, and
`list_id` matches the lists a subscriber was added to when they were created.

## What the agent receives

Each event is a short summary: IDs, an email address, a subject and a link to
the object in your Sequenzy dashboard. Email bodies, custom attributes and
metadata are never sent. The agent reads full details with the regular MCP
tools, for example the conversation tools for a reply.

```json theme={null}
{
  "eventId": "evt_3f2c...",
  "name": "email.replied",
  "timestamp": "2026-10-04T10:00:00.000Z",
  "data": {
    "reply_id": "rep_123",
    "conversation_id": "conv_123",
    "email_send_id": "send_123",
    "subscriber_id": "sub_123",
    "from_email": "jane@example.com",
    "from_name": "Jane",
    "subject": "Re: Our October launch",
    "email_type": "campaign",
    "campaign_id": "camp_123",
    "sequence_id": null,
    "received_at": "2026-10-04T10:00:00.000Z",
    "url": "https://www.sequenzy.com/dashboard/company/<id>/inbox/conv_123"
  },
  "cursor": null
}
```

Text such as a reply subject is written by your contacts. Sequenzy sends it as
data and never adds instructions for the agent to an event.

## How delivery works

These details matter if you build your own MCP client or callback receiver.

* **Discovery.** `server/discover` advertises `events: {}`, and `events/list`
  returns each event with its filters (`inputSchema`) and payload shape
  (`payloadSchema`). Only webhook delivery is offered. A connection without a
  workspace gets an empty list.

* **Workspace.** A subscription belongs to the workspace that was selected
  when it was created. Refreshing or unsubscribing it later works even if the
  connection has since switched to another workspace.

* **Subscribing.** `events/subscribe` needs a `delivery.secret` of `whsec_`
  followed by base64 that decodes to 24-64 bytes, and an HTTPS callback URL that
  does not resolve to a private or local address. Sequenzy sends a signed
  `{"type":"verification","challenge":"..."}` request; the endpoint must return
  a 2xx response echoing the challenge. Redirects are never followed. A
  successful verification is reused for the same connection and URL for 24
  hours.

* **Errors.** A failed verification returns `-32015` with `data.reason` set to
  `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` or
  `challenge_failed`. Other errors:

  | Code | When |
  | - | - |
  | `-32602` | Invalid secret, callback URL, filters or `ttlMs` |
  | `-32011` | Unknown event (`data.kind` is `event`) |
  | `-32012` | The connection lacks the event's permission, or has no usable workspace |
  | `-32013` | The workspace has 25 active subscriptions (`data.limit` is `subscriptions`), or too many verifications for one host (`callback_verifications`) |
  | `-32014` | A delivery mode other than `webhook` (`data.feature` is `deliveryMode`) |

* **Refreshing.** Subscribing again with the same connection, callback URL,
  event and filters refreshes the same subscription and returns a new
  `refreshBefore`. The default lifetime is 7 days. Any `ttlMs` is clamped to
  between 5 minutes and 30 days, and `ttlMs: null` is granted 30 days. Sending a
  new secret rotates it; both secrets sign deliveries for 10 minutes.

* **Signatures.** Each event is one `POST` signed with
  [Standard Webhooks](https://www.standardwebhooks.com): `webhook-id` equals
  `eventId`, plus `webhook-timestamp`, `webhook-signature` and
  `X-MCP-Subscription-Id`. Bodies are at most 256 KiB, and each request times
  out after 10 seconds.

* **Retries.** A failed delivery is retried up to 5 attempts over about 11
  minutes with the same `eventId` and a fresh signature. A `410` response stops
  the subscription until the client subscribes again, and `413` is not retried.
  Events can arrive more than once or out of order, so deduplicate on
  `webhook-id`.

* **Replay.** Events are not replayable, so `cursor` is always `null`. Events
  that happen while a subscription is expired or its endpoint is down past the
  retries are not resent.

* **Stopping.** `events/unsubscribe` stops delivery immediately and can be
  repeated safely. Delivery also stops when the subscription expires or the
  connection loses access to the workspace or event, for example when its API
  key is revoked.

## Limits

* 25 active subscriptions per workspace.
* Up to 600 deliveries per minute per workspace and 120 per minute per
  subscription. Deliveries above those rates are dropped.
* Up to 20 deliveries per workspace in flight at once. Further ones wait for
  up to about 10 minutes, then are dropped.
* 30 callback verifications per minute for each workspace and callback host,
  and 600 per minute for one callback host across all workspaces.
* A new subscription starts receiving events within about a minute.


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