Send Email with Postmark

Overview

Postmark provides multiple endpoints for sending emails:

Choose batch when: sending 2+ distinct emails at once, performance matters, or attachments are needed. Choose single when: sending one email or real-time per-message error handling is needed.

Message Streams (CRITICAL)

Postmark separates emails by intent. Always specify MessageStream:

Never mix transactional and broadcast in the same stream — it damages deliverability. Servers can have up to 10 message streams.

Quick Start

1. Get API Token from your Postmark server settings
2. Verify sender domain or email address
3. Install SDK — see references/installation.md
4. Choose endpoint based on the decision matrix above

Authentication

All API requests require the Server API Token:

X-Postmark-Server-Token: your-server-token-here

Store the token in POSTMARK_SERVER_TOKEN. For testing without sending, use POSTMARK_API_TEST as the token value.

Single Email

Endpoint: POST https://api.postmarkapp.com/email

Required Parameters

Optional Parameters

const postmark = require('postmark');
const client = new postmark.ServerClient(process.env.POSTMARK_SERVER_TOKEN);

const result = await client.sendEmail({
  From: 'notifications@yourdomain.com',
  To: 'customer@example.com',
  Subject: 'Your order has shipped',
  TextBody: 'Your order #12345 is on its way!',
  HtmlBody: '<p>Your order <strong>#12345</strong> is on its way!</p>',
  MessageStream: 'outbound',
  Tag: 'order-shipped'
});

console.log('MessageID:', result.MessageID);

Response includes MessageID — use it for tracking via webhooks or the Messages API.

See references/single-email-examples.md for Python, Ruby, PHP, .NET, and cURL examples.

Batch Email

Endpoint: POST https://api.postmarkapp.com/email/batch

Send up to 500 emails in a single API call. Each message is independently validated and can have its own attachments, tags, and metadata.

const results = await client.sendEmailBatch([
  {
    From: 'sender@yourdomain.com',
    To: 'user1@example.com',
    Subject: 'Order Shipped',
    TextBody: 'Your order has shipped!',
    MessageStream: 'outbound'
  },
  {
    From: 'sender@yourdomain.com',
    To: 'user2@example.com',
    Subject: 'Order Confirmed',
    TextBody: 'Your order is confirmed!',
    MessageStream: 'outbound'
  }
]);

// Check individual results — always handle partial failures
results.forEach((result, index) => {
  if (result.ErrorCode === 0) {
    console.log(`Email ${index + 1} sent: ${result.MessageID}`);
  } else {
    console.error(`Email ${index + 1} failed: ${result.Message}`);
  }
});

For more than 500 emails, chunk the array into groups of 500 and send sequentially. See references/batch-email-examples.md for chunking patterns, attachments, and Python/Ruby/cURL examples.

Send with Template

Endpoint: POST https://api.postmarkapp.com/email/withTemplate

Use server-side Handlebars templates — no client-side rendering needed. Always use TemplateAlias over TemplateId — aliases survive re-creation and work across environments.

const result = await client.sendEmailWithTemplate({
  From: 'sender@yourdomain.com',
  To: 'customer@example.com',
  TemplateAlias: 'order-confirmation',
  TemplateModel: {
    customer_name: 'Jane Doe',
    order_number: 'ORD-67890',
    items: [
      { name: 'Widget', price: '$19.99' },
      { name: 'Gadget', price: '$29.99' }
    ]
  },
  MessageStream: 'outbound'
});

For batch template sends (up to 500), use POST /email/batchWithTemplates via client.sendEmailBatchWithTemplates([...]). See references/template-examples.md for full examples.

Attachments

Include attachments as Base64-encoded content:

{
  "Attachments": [
    {
      "Name": "invoice.pdf",
      "Content": "base64-encoded-content-here",
      "ContentType": "application/pdf"
    }
  ]
}

Embed inline images using ContentID:

{
  "HtmlBody": "<img src=\"cid:logo123\">",
  "Attachments": [
    {
      "Name": "logo.png",
      "Content": "base64-encoded-image",
      "ContentType": "image/png",
      "ContentID": "cid:logo123"
    }
  ]
}

Size limits: TextBody/HtmlBody 5 MB each · Single message with attachments 10 MB · Batch payload 50 MB · Base64 encoding adds ~33% · Certain file types blocked (.exe, .bat)

Tracking

Configure per-email or at server level:

{ "TrackOpens": true, "TrackLinks": "HtmlAndText" }

TrackLinks options: None | HtmlAndText | HtmlOnly | TextOnly

Disable tracking for sensitive transactional emails (password resets, security alerts) to maximize deliverability.

Testing

Never test with fake addresses at real providers (e.g., test@gmail.com) — damages sender reputation.

Error Handling

async function sendWithRetry(client, email, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await client.sendEmail(email);
    } catch (error) {
      const isRetryable = error.statusCode === 429 || error.statusCode === 500;
      if (!isRetryable || attempt === maxRetries) throw error;
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
    }
  }
}

See references/error-handling.md for complete error patterns including batch partial failures and typed error classes.

SMTP

Postmark supports SMTP for legacy integrations — host smtp.postmarkapp.com (transactional) or smtp-broadcasts.postmarkapp.com (broadcast), ports 25/2525/587, Server API Token as username and password. See references/smtp-migration.md for migration examples and custom header reference.

Common Mistakes

Notes

• From address must use a verified domain or sender signature
• Store API key in POSTMARK_SERVER_TOKEN environment variable
• Maximum 50 recipients total per email (To + Cc + Bcc)
• MessageID returned in response is used for bounce/webhook/API correlation
• For broadcast campaigns to large lists, use the Bulk API endpoint (POST /email/bulk)
• Use POSTMARK_API_TEST as the token value in development and CI — validates without sending
• New domains require gradual volume warm-up — see postmark-email-best-practices for the schedule