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

# Receiving events

> Subscribe to receiving events. Receive real-time notifications when messages arrive, security issues are detected, or agents are triggered.

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](/docs/guides/webhooks) 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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).

```json theme={null}
{
  "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"
  }
}
```

## Subscribe to receiving events

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

```typescript theme={null}
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);
```

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

## Handle receiving events

Use the same signature verification flow as sending events. See [handle webhook events](/docs/guides/integrate-webhooks) for the full implementation pattern.

Here is a condensed example handling receiving events:

```typescript theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Set up webhooks" icon="webhook" href="/docs/guides/webhooks">
    Create and configure webhook endpoints
  </Card>

  <Card title="Handle webhook events" icon="code" href="/docs/guides/integrate-webhooks">
    Implement signature verification and event handling
  </Card>

  <Card title="AI agent inboxes" icon="bot" href="/docs/guides/receiving-agents">
    Build automated processing with AI agents
  </Card>

  <Card title="Receiving overview" icon="inbox" href="/docs/guides/receiving-overview">
    Understand the receiving pipeline
  </Card>
</CardGroup>