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
| API | SMTP | |
|---|---|---|
| How you connect | An HTTPS request with a JSON body, with your Server API token in a header | A standard SMTP connection to smtp.postmarkapp.com on port 25, 2525 or 587, with STARTTLS |
| What you change | Your sending code, usually through an official library | A configuration setting |
| When a send fails | You get an answer to every request: success with a message ID, or an error code, for example when a recipient is inactive | Postmark accepts the message and reports problems afterward, through bounce webhooks or the bounces API |
| Sending to many people | The batch endpoint sends up to 500 messages per call | Not part of SMTP. Use the API for batches |
| Retries | Many official libraries retry on network errors for you | Up to your SMTP client |
| Tags | A Tag field on the request | An X-PM-Tag header, one tag per message, up to 1,000 characters |
| Message stream | A MessageStream field on the request | An X-PM-Message-Stream header, or an SMTP Token made for that stream |
| Credentials | Your Server API token, in the X-Postmark-Server-Token header | Your 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
Code
With SMTP
Code
What do you want to do next?
- Send with the APIThe request format, headers and examples, one page at a time.
- Send with SMTPConnection details, authentication and the differences from the API.
- Use an official libraryLibraries for TypeScript, Python, Ruby, .NET, Java, PHP and more.
- Try it without sendingSandbox mode lets you test your setup without delivering real email.
- How SMTP worksA friendly guide to the protocol behind it all.
Prefer a longer read with Python examples? See Sending mission-critical emails in Python: SMTP or API? on the Postmark blog.
Last modified on