Sending Email

Send emails from agent mailboxes with HTML, text, attachments, templates, and scheduling.

Basic Send

Send an email from any agent mailbox.

const email = await tx.agentEmail.send({
  from: 'research-agent@agentmail.usetransactional.com',
  to: 'user@example.com',
  subject: 'Weekly Research Digest',
  html: '<h1>Your Digest</h1><p>Here are this week\'s findings...</p>',
  text: 'Your Digest\n\nHere are this week\'s findings...',
});

Always provide both html and text for maximum deliverability.

Attachments

Attach files up to 25 MB total per message.

await tx.agentEmail.send({
  from: mailbox.address,
  to: 'user@example.com',
  subject: 'Report Attached',
  html: '<p>Please find the report attached.</p>',
  attachments: [
    {
      filename: 'report.pdf',
      content: Buffer.from(pdfBytes).toString('base64'),
      contentType: 'application/pdf',
    },
    {
      filename: 'data.csv',
      content: Buffer.from(csvContent).toString('base64'),
      contentType: 'text/csv',
    },
  ],
});

Multiple Recipients

Send to multiple recipients with CC and BCC support.

await tx.agentEmail.send({
  from: mailbox.address,
  to: ['alice@example.com', 'bob@example.com'],
  cc: ['manager@example.com'],
  bcc: ['audit@internal.com'],
  subject: 'Project Update',
  html: '<p>Latest project status...</p>',
});

Templates

Use Handlebars templates for dynamic content.

await tx.agentEmail.send({
  from: mailbox.address,
  to: 'user@example.com',
  subject: 'Your Research Results',
  template: 'research-results',
  templateData: {
    userName: 'Alex',
    findings: [
      { title: 'Market Analysis', summary: '...' },
      { title: 'Competitor Review', summary: '...' },
    ],
  },
});

Batch Sending

Send to multiple recipients individually (each gets their own copy with personalized data).

await tx.agentEmail.sendBatch({
  from: mailbox.address,
  messages: [
    {
      to: 'alice@example.com',
      subject: 'Your Personalized Report',
      template: 'weekly-report',
      templateData: { name: 'Alice', score: 92 },
    },
    {
      to: 'bob@example.com',
      subject: 'Your Personalized Report',
      template: 'weekly-report',
      templateData: { name: 'Bob', score: 87 },
    },
  ],
});

Scheduled Sending

Schedule emails for future delivery.

await tx.agentEmail.send({
  from: mailbox.address,
  to: 'user@example.com',
  subject: 'Scheduled Follow-up',
  html: '<p>Following up on our conversation...</p>',
  scheduledAt: '2025-01-15T09:00:00Z',
});

Cancel a scheduled email before it sends:

await tx.agentEmail.messages.cancel(email.id);

Custom Headers

Add custom headers for tracking or integration purposes.

await tx.agentEmail.send({
  from: mailbox.address,
  to: 'user@example.com',
  subject: 'Tracked Message',
  html: '<p>Content here</p>',
  headers: {
    'X-Agent-Id': 'research-agent-v2',
    'X-Task-Id': 'task_abc123',
  },
  tags: ['research', 'weekly-digest'],
});

Rate Limits

Each mailbox has independent rate limits:

PlanRate LimitDaily Limit
Free1 msg/sec100/day
Pro10 msg/sec10,000/day
EnterpriseCustomCustom

Next Steps