email.received

​

Payload

{
  "id": "whd_5Rt8mK2pW",
  "event": "email.received",
  "createdAt": "2026-09-11T14:02:37.118Z",
  "data": {
    "messageId": "18f2d3e7a9b1c4f6",
    "threadId": "18f2d1c04b7e9a23",
    "channelId": "chan_4Kp8wN",
    "conversationId": "conv_3Hq9rT",
    "from": "ada@ravennafoods.com",
    "fromName": "Ada Lovell",
    "to": ["sales@acme.com"],
    "cc": [],
    "subject": "Re: Pricing for the Ravenna rollout",
    "receivedAt": "2026-09-11T14:02:31.000Z",
    "folder": "INBOX"
  }
}

​

When it fires

• The sender is outside the workspace. A message sent from any of the workspace’s connected mailboxes, a teammate’s included, delivers email.sent instead.
• The thread is a conversation. A reply in a thread that is already a conversation counts. A new thread counts when the New mail handling setting, or the mailbox’s own override of it, turns it into one. Mail left in the inbox sends nothing.
• The message is not in a spam folder. A message the provider files as spam or junk sends no email event at all.

​

What sends nothing

• A blocked sender. Mail from a sender blocked on that mailbox is moved to the trash.
• A repeat of the same message. Custral skips a message it has processed in the last five minutes. That includes a copy arriving in a second connected mailbox of the workspace, so the message is delivered once, with the channelId of whichever mailbox was processed first.

​

Worth knowing

• No body. The payload carries the subject and the addressing. Read the message itself from the conversation through the Conversations API.
• Ids belong to one mailbox. Each connected mailbox has its own messageId and threadId for the same mail. Key on conversationId to follow a conversation.

​

Example

const KEY_ACCOUNTS = new Set(["ravennafoods.com"]);

custral.on("email.received", async (event) => {
  const {from, subject, conversationId} = event.data;
  const domain = String(from).split("@")[1]?.toLowerCase();
  if (!domain || !KEY_ACCOUNTS.has(domain)) return;

  await alerts.notify({team: "accounts", text: `${from}: ${subject}`, conversationId});
});