Sending Email

Learn how to send transactional emails using the PostaSend API, including HTML, plain text, attachments, and batch sending.

Basic Send

Sending an email requires at minimum a from address, at least one to address, a subject, and either an html or text body. The from address must be a verified domain or email address in your PostaSend account. The API returns a messageId you can use to track the email's delivery status.

typescript
const response = await client.emails.send({
  from: 'Your App <noreply@yourdomain.com>',
  to: ['user@example.com'],
  subject: 'Your order is confirmed',
  html: '<h1>Order #12345 confirmed</h1><p>Thanks for your order!</p>',
  text: 'Order #12345 confirmed. Thanks for your order!',
});

// { messageId: 'msg_abc123', status: 'queued' }

Multiple Recipients

You can send to multiple recipients using the to array. You can also use cc and bcc fields. Each recipient in to, cc, and bcc can be either a plain email address string or an object with name and email fields.

typescript
await client.emails.send({
  from: 'hello@yourdomain.com',
  to: [
    'alice@example.com',
    { name: 'Bob Smith', email: 'bob@example.com' },
  ],
  cc: ['manager@yourdomain.com'],
  bcc: ['audit@yourdomain.com'],
  subject: 'Team update',
  html: '<p>Here is this week's update...</p>',
});

Attachments

Attach files by providing a base64-encoded content string with a filename and content type. Attachments are limited to 25MB total per message. For larger files, consider linking to a URL instead of attaching.

typescript
import fs from 'fs';

const pdfBuffer = fs.readFileSync('./invoice.pdf');

await client.emails.send({
  from: 'billing@yourdomain.com',
  to: ['customer@example.com'],
  subject: 'Your invoice',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    {
      filename: 'invoice-2025-06.pdf',
      content: pdfBuffer.toString('base64'),
      contentType: 'application/pdf',
    },
  ],
});

Custom Headers and Tags

Add custom SMTP headers to your emails for tracking or integration purposes. Use tags to label emails for filtering in the analytics dashboard. Tags must be lowercase alphanumeric strings with hyphens allowed.

typescript
await client.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Password reset',
  html: '<p>Click to reset: <a href="...">Reset password</a></p>',
  tags: ['password-reset', 'auth', 'transactional'],
  headers: {
    'X-Entity-Ref-ID': 'user-456-pwreset',
    'List-Unsubscribe': '<mailto:unsubscribe@yourdomain.com>',
  },
});

Checking Delivery Status

Use the messageId returned from a send call to check the current delivery status of an email. Possible statuses are: queued, sending, delivered, bounced, complained, and failed.

typescript
const message = await client.emails.get('msg_abc123');

console.log(message.status);      // 'delivered'
console.log(message.deliveredAt); // Date object
console.log(message.opens);       // number of opens
console.log(message.clicks);      // number of link clicks
← AuthenticationTemplates →