Postmark
Getting Started

API, or SMTP?

Postmark gives you two ways to send the same email: an HTTP API and a standard SMTP server. Here's how to pick the one that fits the way your app is built.

Which one sounds like you?

Choose the API if…

You're writing the sending code, or you can change it.

  • You want to know right away whether a send worked, with a message ID you can track
  • You send to many people at once: batch up to 500 messages in one call
  • You'd like an official library to handle retries and request details
  • You'd rather hear about a problem when you send than in a bounce report later

Choose SMTP if…

Your app already sends over SMTP and you'd rather not rewrite it.

  • Your app, framework or plugin only has SMTP settings to fill in
  • You're moving from another provider and want to change a setting, not code
  • You want to try Postmark quickly before committing to a rewrite
  • You're fine learning about failures through bounce webhooks or the bounces API

Side by side

APISMTP
How you connectAn HTTPS request with a JSON body, with your Server API token in a headerA standard SMTP connection to smtp.postmarkapp.com on port 25, 2525 or 587, with STARTTLS
What you changeYour sending code, usually through an official libraryA configuration setting
When a send failsYou get an answer to every request: success with a message ID, or an error code, for example when a recipient is inactivePostmark accepts the message and reports problems afterward, through bounce webhooks or the bounces API
Sending to many peopleThe batch endpoint sends up to 500 messages per callNot part of SMTP. Use the API for batches
RetriesMany official libraries retry on network errors for youUp to your SMTP client
TagsA Tag field on the requestAn X-PM-Tag header, one tag per message, up to 1,000 characters
Message streamA MessageStream field on the requestAn X-PM-Message-Stream header, or an SMTP Token made for that stream
CredentialsYour Server API token, in the X-Postmark-Server-Token headerYour Server API token as both username and password, or an SMTP Token (an access key and a secret key)

Quick check

If one of these is true for you, here's where it points.

  • You're starting a new projectAPI
  • You need to know right away if a send failedAPI
  • You send to hundreds of people at onceAPI
  • Your app or plugin only has SMTP settingsSMTP
  • You want to switch providers without touching codeSMTP
  • You're not sureAPI

What each one looks like

With the API

TerminalCode
curl "https://api.postmarkapp.com/email" \ -X POST \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Postmark-Server-Token: server token" \ -d '{ "From": "you@yourdomain.com", "To": "friend@example.com", "Subject": "Hello from Postmark", "TextBody": "It works!", "MessageStream": "outbound" }'

With SMTP

Code
Server smtp.postmarkapp.com Port 587 (25 and 2525 also work) Security STARTTLS Username your Server API token Password your Server API token Header X-PM-Message-Stream: outbound (optional)

What do you want to do next?

Prefer a longer read with Python examples? See Sending mission-critical emails in Python: SMTP or API? on the Postmark blog.

Last modified on