Receiving events

Nuntly emits webhook events for receiving activity so your application can react in real time. You subscribe to these events through the same webhook configuration used for sending events.

Available events

Event	Description
`message.received`	A new email was received and processed.
`message.security.flagged`	A received message failed one or more security checks (SPF, DKIM, or spam).
`message.agent.triggered`	A received message was routed to an AI agent inbox.
`message.sent`	A message was sent from an inbox.

Event payloads

All receiving events follow the same envelope structure. The type field identifies the event, and the data field contains the event-specific payload.

message.received

Emitted when a new email is received and processed.

{
  "type": "message.received",
  "data": {
    "messageId": "imsg_01kabn43yqyxn2bx4ve84mczd3",
    "threadId": "thr_01kabn43yqyxn2bx4ve84mczd3",
    "inboxId": "ibx_01kabn43yqyxn2bx4ve84mczd3",
    "domainName": "yourdomain.com",
    "from": "Jane Doe <sender@example.com>",
    "subject": "Question about my account"
  }
}

message.security.flagged

Emitted when a received message fails one or more security checks (SPF, DKIM, or spam). The message is stored and the thread is marked as spam. Virus-infected emails are rejected at the gateway and never reach this stage.

{
  "type": "message.security.flagged",
  "data": {
    "messageId": "imsg_01kabn43yqyxn2bx4ve84mczd3",
    "threadId": "thr_01kabn43yqyxn2bx4ve84mczd3",
    "inboxId": "ibx_01kabn43yqyxn2bx4ve84mczd3",
    "domainName": "yourdomain.com",
    "from": "suspicious@example.com",
    "subject": "Suspicious message"
  }
}

message.agent.triggered

Emitted when a message arrives at an inbox that has an AI agent assigned. This event is sent in addition to the message.received event.

{
  "type": "message.agent.triggered",
  "data": {
    "messageId": "imsg_01kabn43yqyxn2bx4ve84mczd3",
    "threadId": "thr_01kabn43yqyxn2bx4ve84mczd3",
    "inboxId": "ibx_01kabn43yqyxn2bx4ve84mczd3",
    "agentId": "my-support-agent",
    "domainName": "yourdomain.com",
    "from": "Jane Doe <customer@example.com>",
    "subject": "Help with my order"
  }
}

message.sent

Emitted when a message is sent from an inbox (via send, reply, or forward).

{
  "type": "message.sent",
  "data": {
    "messageId": "imsg_01kabn43yqyxn2bx4ve84mczd3",
    "threadId": "thr_01kabn43yqyxn2bx4ve84mczd3",
    "inboxId": "ibx_01kabn43yqyxn2bx4ve84mczd3",
    "domainName": "yourdomain.com",
    "from": "Support <support@yourdomain.com>",
    "subject": "Re: Help with my order"
  }
}

Add receiving events to your webhook configuration the same way you add sending events. You can subscribe through the dashboard or the SDK.

import { Nuntly } from '@nuntly/sdk';

const nuntly = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
});

const webhook = await nuntly.webhooks.create({
  name: 'Receiving listener',
  endpointUrl: 'https://yourapp.com/api/webhooks/receiving',
  status: 'enabled',
  events: [
    'message.received',
    'message.security.flagged',
    'message.agent.triggered',
    'message.sent',
  ],
});

console.log('Webhook ID:', webhook.id);
console.log('Signing secret:', webhook.signingSecret);

The signing secret is displayed only once. Store it securely. You need it to verify incoming webhook requests.

Handle receiving events

Use the same signature verification flow as sending events. See handle webhook events for the full implementation pattern. Here is a condensed example handling receiving events:

// Inside your webhook handler (after signature verification)
const event = JSON.parse(payload);

switch (event.type) {
  case 'message.received':
    console.log(`New message from ${event.data.from}: ${event.data.subject}`);
    break;
  case 'message.security.flagged':
    console.log(`Flagged message from ${event.data.from}: ${event.data.subject}`);
    break;
  case 'message.agent.triggered':
    console.log(`Agent ${event.data.agentId} triggered for message ${event.data.messageId}`);
    // Trigger your AI agent processing
    break;
  case 'message.sent':
    console.log(`Message sent to ${event.data.toAddresses.map(a => a.address).join(', ')}`);
    break;
}

Learn more

Set up webhooks

Create and configure webhook endpoints

Handle webhook events

Implement signature verification and event handling

AI agent inboxes

Build automated processing with AI agents

Receiving overview

Understand the receiving pipeline

Getting started

Sending

Receiving

Configuration

Observability

Webhooks

Best practices

Libraries & tools

Receiving events

Available events

Event payloads

message.received

message.security.flagged

message.agent.triggered

message.sent

Handle receiving events

Learn more

Set up webhooks

Handle webhook events

AI agent inboxes

Receiving overview

​Available events

​Event payloads

​message.received

​message.security.flagged

​message.agent.triggered

​message.sent

​Subscribe to receiving events

​Handle receiving events

​Learn more

Set up webhooks

Handle webhook events

AI agent inboxes

Receiving overview

Available events

Event payloads

message.received

message.security.flagged

message.agent.triggered

message.sent

Subscribe to receiving events

Handle receiving events

Learn more