Receiving email

AgenticEmail pushes events to you the moment they happen, so your agents act on new mail in milliseconds instead of polling. There are two ways to receive them: webhooks and a WebSocket stream.

Webhooks

Register an endpoint and choose which events to subscribe to. AgenticEmail signs every request so you can verify it came from us.

await client.webhooks.create({
  url: "https://your-app.com/api/agenticemail",
  events: ["message.received", "message.delivered", "message.bounced"],
});

Your endpoint receives a JSON payload for each event:

{
  "type": "message.received",
  "inboxId": "inbox_123",
  "message": {
    "id": "msg_456",
    "from": "customer@example.com",
    "to": "support-agent@inbox.agenticemail.com",
    "subject": "Re: Thanks for reaching out",
    "text": "Actually, I have one more question...",
    "receivedAt": "2026-07-04T12:00:00Z"
  }
}

Verify the AgenticEmail-Signature header against your webhook secret before trusting the payload.

import { verifyWebhook } from "@agenticemail/sdk";

const event = verifyWebhook({
  payload: rawBody,
  signature: req.headers["agenticemail-signature"],
  secret: process.env.AGENTICEMAIL_WEBHOOK_SECRET,
});

WebSocket events

For live UIs and long-running agents, subscribe to a real-time stream instead. You get the same events without exposing a public endpoint.

const stream = client.events.stream({ inboxId: inbox.id });

stream.on("message.received", (message) => {
  console.log("New mail:", message.subject);
});

for event in client.events.stream(inbox_id=inbox.id):
    if event.type == "message.received":
        print("New mail:", event.message.subject)

Event types

• message.received - a new inbound message arrived in an inbox.
• message.delivered - an outbound message was accepted by the recipient server.
• message.opened - a recipient opened a tracked message.
• message.bounced - an outbound message could not be delivered.