Docs / Sending and domains

Migrating from Postmark

You can keep sending through your Postmark server: connect it under Sending providers (server token, plus the account token if you want OneSend to manage the domain) and OneSend routes through it.

Option 1: the compatibility endpoints

PostmarkOneSend
POST /emailPOST /compat/postmark/email
POST /email/batchPOST /compat/postmark/email/batch (up to 500)
POST /email/withTemplatePOST /compat/postmark/email/withTemplate
POST /email/batchWithTemplatesPOST /compat/postmark/email/batchWithTemplates

Authenticate with the X-Postmark-Server-Token header carrying a OneSend API key, as the Postmark libraries do. Authorization: Bearer is not accepted on these endpoints. Responses use Postmark's shape: { "To", "SubmittedAt", "MessageID", "ErrorCode": 0, "Message": "OK" }, where MessageID is the OneSend email id. Batch requests return one result per message; check ErrorCode in each, as with Postmark.

With the Postmark Node.js library, set the request host:

const postmark = require('postmark');
const client = new postmark.ServerClient(process.env.ONESEND_API_KEY, { requestHost: 'mail.example.com/compat/postmark' });
await client.sendEmail({ From: 'hello@acme.dev', To: 'ada@example.com', Subject: 'Hello', TextBody: 'Hi' });

Check the option name against the library version you use. With plain HTTP, replace https://api.postmarkapp.com with https://<your server>/compat/postmark.

Field mapping

PostmarkOneSendNotes
From, Subject, HtmlBody, TextBodyfrom, subject, html, text
To, Cc, Bcc, ReplyTo (comma-separated)listsQuoted names with commas are kept together. At most 50 recipients across To, Cc and Bcc.
Tagtags: [Tag]
Metadatametadata
Headers: [{ Name, Value }]headersReserved headers (To, From, Subject, …) are refused, as in /v1/emails.
TrackOpenstracking.opens
TrackLinkstracking.clicksNone turns click tracking off; any other value turns it on for HTML links. Text-only link tracking is not available.
MessageStreamtypeA stream whose name contains broadcast sends as marketing (List-Unsubscribe headers, campaign providers only). Others send as transactional.
Attachments: [{ Name, Content, ContentType }]attachments
TemplateId or TemplateAlias, TemplateModeltemplate, variablesA OneSend template id or slug. OneSend templates use {{variable}} syntax; check sections and loops after moving a Postmark template.

Ignored (listed in X-OneSend-Ignored-Fields): InlineCss (OneSend templates are already inlined), attachment ContentID (inline images).

Errors use Postmark's shape { "ErrorCode", "Message" }: 401 with code 10 for a missing or invalid token, and 422 with code 300 (invalid request), 400 (the key may not send from this domain), 402 (invalid JSON), 405 (the key may not send), 1101 (template not found) or 410 (more than 500 messages).

Other Postmark APIs (bounces, message streams, templates, stats) have no compat equivalent. Use /v1/emails, /v1/suppressions, /v1/templates and /v1/statistics/overview.

Option 2: the native API

PostmarkOneSend
client.sendEmail(...)onesend.emails.send(...) or POST /v1/emails
client.sendEmailBatch([...])POST /v1/emails/batch (up to 100 per request)
client.sendEmailWithTemplate(...)template + variables on /v1/emails
Broadcast streamtype: "broadcast", or campaigns (/v1/campaigns)
WebhooksOneSend webhooks (Webhooks)

DNS

Keep Postmark's DKIM record (<date>pm._domainkey) and its custom Return-Path CNAME (pm-bounces.<domain>). Postmark's SPF is handled by the Return-Path, so your root SPF needs no Postmark include. Add the _onesend-verify TXT record and records for any providers you add.

Suppressions

Export inactive recipients (hard bounces, spam complaints, manual suppressions) per message stream from Postmark and import them as described in the cutover checklist. Suppressions from a broadcast stream map to "scope":"broadcast".

Then follow the general cutover checklist.