Transactional

Quickstart

Create a mailbox, send an email, and read your inbox in 5 minutes.

Prerequisites

  • A Transactional account with an API key
  • Node.js 18+ or any HTTP client

Install the SDK

npm install @usetransactional/node

1. Create a Mailbox

Every agent needs a mailbox — a dedicated email address it can send from and receive mail at.

import { Transactional } from '@usetransactional/node';
 
const tx = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY,
});
 
const mailbox = await tx.agentEmail.mailboxes.create({
  name: 'research-agent',
  domain: 'agentmail.usetransactional.com',
});
 
console.log(mailbox.address);
// → research-agent@agentmail.usetransactional.com
console.log(mailbox.id);
// → mbx_abc123

You can also use a custom domain for branded addresses like agent@yourdomain.com.

2. Send an Email

Send an email from your agent's mailbox.

const email = await tx.agentEmail.send({
  from: mailbox.address,
  to: 'user@example.com',
  subject: 'Research Complete',
  html: '<p>Here are the findings from your research request.</p>',
  text: 'Here are the findings from your research request.',
});
 
console.log(email.id);
// → msg_xyz789
console.log(email.status);
// → 'queued'

3. Read the Inbox

Check for new messages in your agent's mailbox.

const messages = await tx.agentEmail.inbox.list({
  mailbox: mailbox.id,
  unread: true,
});
 
for (const message of messages.data) {
  console.log(`From: ${message.from}`);
  console.log(`Subject: ${message.subject}`);
  console.log(`Preview: ${message.textPreview}`);
}

4. Reply to a Message

Reply to an incoming message. Threading is handled automatically.

await tx.agentEmail.reply({
  messageId: messages.data[0].id,
  html: '<p>Thanks for the follow-up. Updated findings are attached.</p>',
});

The reply will automatically include the correct In-Reply-To and References headers to maintain the thread.

5. Set Up Webhooks (Optional)

Instead of polling, receive real-time notifications when new emails arrive.

await tx.agentEmail.webhooks.create({
  mailbox: mailbox.id,
  url: 'https://yourapp.com/webhooks/agent-email',
  events: ['message.received', 'message.bounced'],
});

See Webhooks for event types and HMAC verification.

Next Steps