Skip to main content
An AI agent inbox turns email into a structured input channel for your AI models. Instead of polling for new emails or building a custom IMAP listener, you assign an agent identifier to an inbox and receive a webhook event every time a message arrives. Your agent reads the message, decides what to do, and responds, all through the API. This pattern works for any scenario where you want an LLM to handle email autonomously: customer support, intake triage, lead qualification, invoice processing, order acknowledgment, or any custom workflow that starts with an inbound email.

​
How it works

1

Assign an agent to an inbox

Set the agentId field on an inbox to your agent’s identifier. This can be any string, a name, a UUID, or a reference to your agent registry.
2

Receive the webhook

When a message arrives at an agent-enabled inbox, Nuntly emits both message.received and message.agent.triggered. Your server receives the event with the message ID and thread context.
3

Read and process

Your agent fetches the message content through the API, full text, HTML, and attachments. It loads any stored conversation state, then calls your AI model with the message and context.
4

Respond and remember

Your agent sends a reply through the API, which is added to the same thread and delivered via email. It then saves updated conversation state so the next message in the thread has the full context.

​
Assign an agent to an inbox

Set agentId when creating or updating an inbox. 
import { Nuntly } from '@nuntly/sdk';

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

// On creation
const inbox = await nuntly.inboxes.create({
  domainId: 'your-domain-id',
  address: 'ai-support',
  name: 'AI Support Agent',
  agentId: 'support-agent-v1',
});

// Or update an existing inbox
await nuntly.inboxes.update('ibx_01kabn43yqyxn2bx4ve84mczd3', {
  agentId: 'support-agent-v1',
});

// Remove the agent from an inbox
await nuntly.inboxes.update('ibx_01kabn43yqyxn2bx4ve84mczd3', {
  agentId: null,
});

​
Webhook event

When a message arrives at an inbox with an agentId, Nuntly emits a message.agent.triggered event in addition to message.received. Subscribe to this event in your webhook configuration. See receiving events for the full event payload.

​
Agent state

The agent state API lets your agent persist data between messages. This is how your agent maintains context across a multi-email conversation: customer preferences, ticket status, prior summaries, or any structured data your model needs. State is scoped at three levels:
ScopeWhen to use
GlobalPreferences or configuration that apply across all of the agent’s inboxes.
Per inboxState shared across all threads in an inbox (for example, team settings).
Per threadConversation context specific to one exchange. This is the most common scope.
State is a JSON object (maximum 8 KB). You can also store a summary string (maximum 4 KB), useful for a condensed narrative of the conversation that you pass to your model without replaying the full history.

​
Get state

// Thread-scoped state (most common)
const state = await nuntly.agents.getState('support-agent-v1', {
  inboxId: 'ibx_01kabn43yqyxn2bx4ve84mczd3',
  threadId: 'thr_01kabn43yqyxn2bx4ve84mczd3',
});

console.log('Stored state:', state.data.state);
console.log('Summary:', state.data.summary);

​
Upsert state

await nuntly.agents.upsertState('support-agent-v1', {
  inboxId: 'ibx_01kabn43yqyxn2bx4ve84mczd3',
  threadId: 'thr_01kabn43yqyxn2bx4ve84mczd3',
  state: {
    status: 'awaiting-customer-reply',
    ticketId: 'TICKET-1234',
    priority: 'high',
  },
  summary: 'Customer reported a billing discrepancy. Escalated to billing team and awaiting confirmation.',
});

​
Complete example with Claude

The following example shows a complete agent handler using the Claude API. It receives the message.agent.triggered webhook, reads the email, loads stored conversation context, generates a reply with Claude, sends the reply, and saves updated state. 
import Anthropic from '@anthropic-ai/sdk';
import { Nuntly } from '@nuntly/sdk';

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

const AGENT_ID = 'support-agent-v1';

export async function handleAgentTriggered(event: {
  type: 'message.agent.triggered';
  data: { messageId: string; threadId: string; inboxId: string };
}) {
  const { messageId, threadId, inboxId } = event.data;

  // 1. Retrieve message metadata and content
  const [message, content] = await Promise.all([nuntly.messages.retrieve(messageId), nuntly.messages.getContent(messageId)]);

  const bodyText = content.data.textUrl ? await fetch(content.data.textUrl).then((r) => r.text()) : '(no plain text body)';

  // 2. Load stored conversation state for this thread
  const stored = await nuntly.agents.getState(AGENT_ID, { inboxId, threadId });
  const previousSummary = stored?.data?.summary ?? null;

  // 3. Build the prompt and call Claude
  const systemPrompt = [
    'You are a helpful customer support agent. Reply professionally and concisely.',
    previousSummary ? `Previous conversation summary: ${previousSummary}` : null,
  ]
    .filter(Boolean)
    .join('\n\n');

  const aiResponse = await anthropic.messages.create({
    model: 'claude-opus-4-5',
    max_tokens: 1024,
    system: systemPrompt,
    messages: [
      {
        role: 'user',
        content: `From: ${message.data.fromAddress}\nSubject: ${message.data.subject}\n\n${bodyText}`,
      },
    ],
  });

  const replyText = aiResponse.content[0].type === 'text' ? aiResponse.content[0].text : '';

  // 4. Send the reply, it is added to the same thread
  await nuntly.messages.reply(messageId, {
    text: replyText,
    html: `<p>${replyText.replace(/\n\n/g, '</p><p>').replace(/\n/g, '<br>')}</p>`,
  });

  // 5. Update conversation state with a fresh summary
  const summaryResponse = await anthropic.messages.create({
    model: 'claude-haiku-4-5-20251001',
    max_tokens: 256,
    messages: [
      {
        role: 'user',
        content: `Summarize this support exchange in 2-3 sentences:\n\nCustomer: ${bodyText}\n\nAgent: ${replyText}`,
      },
    ],
  });

  const newSummary = summaryResponse.content[0].type === 'text' ? summaryResponse.content[0].text : '';

  await nuntly.agents.upsertState(AGENT_ID, {
    inboxId,
    threadId,
    state: {
      lastMessageId: messageId,
      lastAction: 'replied',
      messageCount: (stored?.data?.state?.messageCount ?? 0) + 1,
    },
    summary: newSummary,
  });
}
The summary is generated by a faster model to keep latency low. It replaces the previous summary on each turn, acting as a rolling context window rather than a growing history.

​
Multi-agent platforms

You can run multiple specialized agents across different inboxes, each with its own agentId and state. Use namespaces to group an agent’s inboxes together. For example, a platform with a support agent, a billing agent, and a sales agent might look like: 
// Each agent has its own namespace for isolation
const supportNamespace = await nuntly.namespaces.create({ name: 'Support Agent', externalId: 'agent:support' });
const billingNamespace = await nuntly.namespaces.create({ name: 'Billing Agent', externalId: 'agent:billing' });

// Inboxes are scoped to the right namespace and agent
await nuntly.inboxes.create({
  domainId: 'your-domain-id',
  address: 'support',
  namespaceId: supportNamespace.data.id,
  agentId: 'support-agent-v1',
});

await nuntly.inboxes.create({
  domainId: 'your-domain-id',
  address: 'billing',
  namespaceId: billingNamespace.data.id,
  agentId: 'billing-agent-v1',
});
Each agent receives only its own message.agent.triggered events and manages its own state independently.

​
Next steps

Receiving events

See the full payload for agent-triggered events

Send, reply, and forward

Learn how agents can send replies from inboxes

Namespaces

Organize agent inboxes with namespaces