Setting Up Postmark

Last lesson you learned what Postmark is and how servers and message streams fit together. Now it's hands-on time. You'll set up an account, prove you own the address you're sending from and fire off a real email with a few lines of Node.

Your Account and Server#

Step 1. Create an Account#

Sign up on the Postmark website. New accounts start on the free developer plan, so you don't have to pay a dime to follow along.

You'll need an email address on a domain you own, like [email protected]. Postmark has to be able to check DNS records for authentication, so free addresses from providers like Gmail or Yahoo won't work as a sending address.

Step 2. Create or Open a Server#

Quick refresher... a server is a folder for one project. Log in, go to Servers, and either pick your first server or create a new one. A good habit is naming it after your app and environment, like my-app-production.

Step 3. Copy the Server API Token#

Inside your server, open the API Tokens tab and copy the Server API token. That's the secret key your code uses to send email through this server.

Postmark also has an Account API token, which lives on the API Tokens page in the Account section. That one's for admin jobs like creating servers and adding sender signatures or domains. For actually sending email, you want the Server token.

Prove You Own the Sending Address#

Email providers won't trust mail from an address nobody has proven. Postmark gives you two ways to prove it.

Sender Signatures#

A sender signature is the email address that shows up in the From field of your messages. Postmark's rule is that you need a sender signature set up for each address you want to send from.

To add one, you type in the address and Postmark sends a confirmation email to that mailbox. You click the link, and that one address is confirmed. Done.

This is the quickest route when you only ever send from one address.

Domain Verification#

Domain verification proves you own the whole domain instead of just one address. Postmark says this "will allow you to send from any email address on a particular domain." Once the domain's verified, you don't have to add separate sender signatures for addresses on it.

Domain verification works by adding DNS records. DNS is the internet's address book for your domain, and your DNS provider has a page where you add records.

DKIM, Return-Path and DMARC#

These three records sound intimidating. Each one only has ONE simple job though.

Step 1. Add the DKIM Record#

DKIM is a digital signature on your emails. It lets inbox providers check that a message really came from your domain and didn't get tampered with along the way.

In Postmark, open your Sender Signatures page, find your domain and select DNS Settings. Postmark shows you a DKIM record there. Over in your DNS provider, add a new TXT record using the Hostname and Value from that page.

Postmark says DKIM will show as verified within 48 hours. You can click the Verify button to check sooner. Once DKIM is verified, Postmark starts signing the emails it sends for your domain.

Step 2. Add the Return-Path Record#

The Return-Path is the address where bounces and other email feedback get sent. Setting a custom Return-Path on your own domain helps your emails line up with your domain when they get checked for authentication.

On that same DNS Settings page, Postmark lists the Return-Path values. In your DNS provider, add a new CNAME record with the Hostname and Value shown there. The value is pm.mtasv.net.

Same as DKIM, it can take up to 48 hours to show as verified, and the Verify button lets you check sooner. Postmark says that once this record is verified, messages it sends for your domain start passing SPF alignment.

Step 3. Add a DMARC Record#

DMARC is a rule you publish that tells inbox providers what to do with email claiming to be from your domain when it fails the DKIM and SPF checks. Postmark describes it as "a standard that allows you to set policies on who can send email for your domain based on DKIM and SPF."

Postmark recommends starting with a policy of p=none. That setting tells inbox providers not to take action yet, and it gets you reports about who's sending email using your domain. Postmark's domain article links to a step by step DMARC walkthrough, and Postmark also has a free DMARC report tool called DMARC Digests.

Send Your First Email from Node#

Step 1. Install the Library#

Postmark's official Node library is the postmark package on npm. Postmark's quick start lists Node.js 18 or newer.

npm install postmark

Step 2. Store the Token in an Environment Variable#

Drop your Server API token into your .env file, using the variable name from Postmark's own example.

POSTMARK_SERVER_TOKEN=your_server_token

Make sure .env is in your .gitignore.

Step 3. Send the Email#

Postmark's library hands you a ServerClient. You create one with your token, then call sendEmail. This example follows Postmark's own example, written as plain JavaScript, with both an HTML body and a plain text body added in.

Create a file called send.mjs in the same folder as your .env file and paste this in. The .mjs ending tells Node.js to treat the file as a module, which is what lets it use import and an await outside a function.

import { ServerClient } from "postmark";
 
const client = new ServerClient(process.env.POSTMARK_SERVER_TOKEN);
 
const result = await client.sendEmail({
  From: "[email protected]",
  To: "[email protected]",
  Subject: "Test",
  HtmlBody: "<p>Hello from Postmark!</p>",
  TextBody: "Hello from Postmark!",
  MessageStream: "outbound",
});
 
console.log(result.MessageID);

Here's what each field is doing.

• From is your sender address. It has to be a confirmed sender signature or an address on your verified domain.
• To is who gets the email.
• Subject is the subject line.
• HtmlBody is the styled version of the email.
• TextBody is the plain text version, for email apps that don't show HTML.
• MessageStream picks the lane. outbound is the ID of the default Transactional stream.

Now run it. The --env-file flag tells Node.js to load your .env file first, so process.env.POSTMARK_SERVER_TOKEN actually has a value.

node --env-file=.env send.mjs

The --env-file flag needs Node.js 20.6 or newer. On an older version, install the dotenv package and add import "dotenv/config"; as the very first line of send.mjs, then run node send.mjs.

If you write this in TypeScript instead, you might see Postmark's examples stick a ! after process.env.POSTMARK_SERVER_TOKEN. That tells TypeScript you're sure the value is set. It's a TypeScript-only thing, so leave it out of a .mjs file.

Postmark's docs point to MessageID as the most useful field in the response. It's a unique ID you can use to track delivery, bounces and opens.

Step 4. Test Without Sending Anything#

Postmark also lets you send test emails that never get delivered. Use POSTMARK_API_TEST as your server token and the API accepts the request without actually delivering anything. Super handy for making sure your code works BEFORE you aim it at a real inbox.

TL;DR#

• A server organizes one project, and its Server API token is the key your code sends with
• The Account API token is for admin jobs, not for sending email
• A sender signature confirms one address, while domain verification covers every address on the domain
• DKIM is a TXT record, the custom Return-Path is a CNAME record pointing to pm.mtasv.net, and DMARC can start at p=none
• You don't need to add Postmark to your SPF record
• Install with npm install postmark, create a ServerClient and call sendEmail
• Keep the token in POSTMARK_SERVER_TOKEN, never in your code

What's Next?#

Once that first email lands, try moving the send into a real moment in your app, like the "confirm your email" step right after signup.