Postmark Getting Started: Account, Keys, First Email (2026)

Getting started overview

To begin sending emails with Postmark, developers typically follow a sequence involving account creation, server setup, API key retrieval, and domain verification. Postmark maintains a distinction between transactional and broadcast email streams to optimize deliverability for time-sensitive messages Postmark Developer Documentation.

The core components for integration include:

• Account and Server: Your primary organizational unit for email sending.
• API Token: The credential used to authenticate your requests.
• Sending Domain: Verified domain from which your emails will originate.
• API Endpoint: The specific URL to which you send email requests.
• Client Library (SDK) or HTTP Request: Your method for interacting with the API.

The following table outlines the initial steps:

Create an account and get keys

To access the Postmark API, you must first create an account and obtain an API token. Postmark distinguishes between account-level API tokens and server-level API tokens. For sending emails and retrieving server-specific data, a Server API Token is required Postmark API Authentication Guide.

1. Sign Up for a Postmark Account

Navigate to the Postmark registration page. Provide the necessary details to set up your account. Postmark offers a free tier that includes 100 emails per month, suitable for initial testing and development Postmark Pricing Information.

2. Create a Server

After signing up, you will be prompted to create your first server. A server in Postmark acts as a container for your sending domains, API tokens, and email streams (transactional or broadcast). You can name your server to reflect the application or environment it will serve (e.g., MyWebApp-Production, Staging-Environment). Each server has its own distinct API token, which helps in isolating email traffic and managing credentials.

3. Retrieve Your Server API Token

Once your server is created:

1. Log in to your Postmark dashboard.
2. Select the server you intend to use from the 'Servers' list.
3. Navigate to the 'API Tokens' section within that server's settings.
4. Your Server API Token will be displayed. This token is a UUID (e.g., xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Security Note: Treat your Server API Token as a sensitive credential. It grants full access to send emails and manage settings for that specific server. Do not hardcode it directly into client-side code, commit it to public repositories, or share it unnecessarily. Best practices include using environment variables for server-side applications or secure secret management systems.

4. Add and Verify a Sending Domain

Before sending emails, you must configure and verify a sending domain. This process ensures that Postmark is authorized to send emails on behalf of your domain, which is crucial for email deliverability and preventing spoofing.

1. From your server's dashboard, go to 'Sender Signatures'.
2. Click 'Add a domain' or 'Add a Sender Signature'.
3. Enter your domain (e.g., example.com).
4. Postmark will provide DNS records (TXT, MX, CNAME) that you need to add to your domain's DNS settings.
5. Once these records are propagated and Postmark detects them, your domain will be marked as verified. This process can take minutes to several hours depending on your DNS provider.

Verified domains improve sender reputation and are essential for production use cases Postmark Sending Domain Setup Guide. Incorrect or missing DNS records can lead to emails being marked as spam or rejected by recipient mail servers.

Your first request

With an active Postmark account, a server-level API token, and a verified sending domain, you can proceed to send your first email. Postmark supports sending emails via its REST API or through various official and community-contributed SDKs.

Using the REST API (cURL Example)

The most direct way to send an email is by making an HTTP POST request to Postmark's /email endpoint. The request must include your Server API Token in the X-Postmark-Server-Token HTTP header and a JSON payload with email details.

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

curl -X POST "https://api.postmarkapp.com/email" \ 
     -H "Accept: application/json" \ 
     -H "Content-Type: application/json" \ 
     -H "X-Postmark-Server-Token: YOUR_SERVER_API_TOKEN" \ 
     -d '{ "From": "[email protected]", "To": "[email protected]", "Subject": "Hello from Postmark!", "HtmlBody": "<strong>Hello</strong> dear Postmark user.", "TextBody": "Hello dear Postmark user.", "MessageStream": "outbound" }'

Replace YOUR_SERVER_API_TOKEN with your actual token and [email protected] with an email address from your verified sending domain. The MessageStream parameter, set to "outbound", specifies that the email is a transactional message. Postmark also supports a "broadcast" stream for marketing emails, though its primary focus is transactional email Postmark Send Email API Reference.

Using an SDK (Node.js Example)

Postmark provides official SDKs for several languages, simplifying API interaction. Here's an example using the Node.js SDK:

1. Install the SDK

npm install postmark

2. Send an Email

const postmark = require("postmark");
const client = new postmark.ServerClient("YOUR_SERVER_API_TOKEN");

async function sendFirstEmail() {
  try {
    const response = await client.sendEmail({
      "From": "[email protected]",
      "To": "[email protected]",
      "Subject": "Hello from Postmark! (via Node.js)",
      "HtmlBody": "<strong>Hello</strong> dear Postmark user, from Node.js.",
      "TextBody": "Hello dear Postmark user, from Node.js.",
      "MessageStream": "outbound" // Specify transactional stream
    });
    console.log("Email sent successfully:", response);
  } catch (error) {
    console.error("Error sending email:", error);
  }
}

sendFirstEmail();

Ensure that YOUR_SERVER_API_TOKEN and the email addresses are correctly substituted. The MessageStream value of "outbound" indicates a transactional email, leveraging Postmark's dedicated infrastructure for high deliverability. For more SDK examples, refer to the Postmark Libraries and SDKs page.

Common next steps

After successfully sending your first email, consider these steps to integrate Postmark more deeply into your application:

• Templates: Postmark supports templating for dynamic email content. You can design email templates within the Postmark dashboard or provide them in your API calls, using Handlebars-like syntax for variable substitution Postmark Email Templates Guide.
• Webhooks: Set up webhooks to receive real-time notifications about email delivery status (delivered, bounced, opened, clicked, etc.). This is critical for monitoring deliverability and handling bounces programmatically Postmark Webhooks Overview. Webhooks are a common pattern for asynchronous event notification in many APIs, including payment gateways like Stripe's webhook documentation and messaging platforms like Twilio's webhook security guide.
• Sender Signatures (Advanced): For applications sending from multiple domains or specific subdomains, configure additional sender signatures.
• Message Streams: While "outbound" is for transactional emails, consider a "broadcast" stream for marketing-related communications if your use case requires it, although Postmark emphasizes transactional email.
• Error Handling: Implement robust error handling in your code to gracefully manage API failures, such as invalid tokens or malformed requests. Postmark's API returns descriptive error codes and messages.
• Inbound Email: If your application needs to process replies or receive emails, configure inbound email processing by setting up MX records to point to Postmark's inbound servers Postmark Inbound Email Guide.

Troubleshooting the first call

If your initial email sending attempt fails, review these common issues:

• Invalid Server API Token: Double-check that the API token used in your request exactly matches the Server API Token from your Postmark dashboard. Ensure no leading/trailing spaces or typos.
• Unverified Sending Domain: The From email address must belong to a domain that has been fully verified in Postmark. Check the 'Sender Signatures' section in your dashboard for verification status. Missing or incorrect DNS records are a frequent cause.
• Incorrect JSON Payload: Ensure your JSON body is well-formed and contains all required fields (From, To, Subject, and at least one of HtmlBody or TextBody). Pay attention to quotes and commas.
• Missing HTTP Headers: Verify that the X-Postmark-Server-Token, Accept: application/json, and Content-Type: application/json headers are correctly set in your HTTP request.
• Network Issues/Firewall: Confirm that your server or development environment can reach api.postmarkapp.com over HTTPS (port 443).
• Rate Limits: For initial testing, this is unlikely, but be aware that Postmark enforces API rate limits.
• Dashboard Activity: Check your Postmark dashboard's 'Activity' feed for details on failed sends. This often provides specific error messages directly from Postmark.
• Message Stream: Ensure you are specifying a valid MessageStream (e.g., "outbound") if you are explicitly including it.