SMTP relay

Connection settings#

These are the only values you need. The same settings are on the API keys page of the dashboard, under SMTP configuration.

A mailbox can also sign in here with its full address and mailbox password instead of an API key — that is how Thunderbird, Apple Mail and Outlook send. The differences are listed under Mailbox credentials.

Ports and TLS#

Both ports land on the same relay; they differ only in how TLS starts. The relay looks at the first byte your client sends: a TLS ClientHello means implicit TLS, and a client that sends nothing and waits for a greeting is treated as STARTTLS.

On a plaintext connection to 587 the relay answers only EHLO, HELO, STARTTLS and QUIT. Any other command — AUTH, MAIL FROM — is answered with 530 5.7.0 Must issue STARTTLS first, so a password can never cross the wire unencrypted. There is no unencrypted port and no port 2525 for submission.

The certificate is a Let's Encrypt certificate for poststack.dev that also names smtp.poststack.dev, so verification succeeds with the host above. After TLS the relay advertises AUTH PLAIN LOGIN, SIZE 37748736, 8BITMIME, SMTPUTF8 and PIPELINING.

Send your first message#

1. Verify the domain you send from

   The address in From must be on a domain that is verified on your team. A message from any other domain is refused at the end of DATA with 550 Domain 'example.com' not found for this team or … is not verified. See Domains.

2. Create an API key

   Any key works — Full access or Sending only. A key restricted to one domain can only send from that domain; anything else gets 550 API key is restricted to a different domain. See Authentication.

3. Point your mailer at the relay

   Node.jsPythonGo

   Copy

   import nodemailer from 'nodemailer';
   
   const transporter = nodemailer.createTransport({
     host: 'smtp.poststack.dev',
     port: 587,
     secure: false,      // start in plaintext…
     requireTLS: true,   // …and refuse to continue unless STARTTLS succeeds
     auth: {
       user: 'poststack',                     // any value when the password is an API key
       pass: process.env.POSTSTACK_API_KEY,   // sk_live_…
     },
   });
   // Implicit TLS instead: port: 465, secure: true (drop requireTLS).
   
   const info = await transporter.sendMail({
     from: 'Acme <hello@yourdomain.com>',
     to: 'user@example.com',
     subject: 'Welcome to Acme',
     html: '<p>Thanks for signing up.</p>',
     text: 'Thanks for signing up.',
     headers: {
       'X-PostStack-Tags': 'welcome,onboarding',
     },
   });
   console.log(info.response); // "250 OK: message queued"

4. Find it in the dashboard

   A live send is answered 250 OK: message queued; the email id is not part of that reply. The message appears under Emails within a second, with the same statuses and webhook events as an API send. Tag it with X-PostStack-Tags to find it again.

Framework settings#

Every framework mailer needs the same four values. These use port 587 with STARTTLS and read the key from an environment variable.

# settings.py
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.poststack.dev"
EMAIL_PORT = 587
EMAIL_USE_TLS = True          # STARTTLS. For port 465 use EMAIL_USE_SSL = True instead.
EMAIL_HOST_USER = "poststack"
EMAIL_HOST_PASSWORD = os.environ["POSTSTACK_API_KEY"]
DEFAULT_FROM_EMAIL = "Acme <hello@yourdomain.com>"

# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: "smtp.poststack.dev",
  port: 587,
  user_name: "poststack",
  password: ENV["POSTSTACK_API_KEY"],
  authentication: :plain,
  enable_starttls_auto: true
}

# .env — Symfony Mailer upgrades with STARTTLS on 587 by itself
MAIL_MAILER=smtp
MAIL_HOST=smtp.poststack.dev
MAIL_PORT=587
MAIL_USERNAME=poststack
MAIL_PASSWORD=sk_live_...
MAIL_FROM_ADDRESS=hello@yourdomain.com

Step-by-step guides for these and other stacks are under Framework guides — for example Django, Laravel and Ruby.

PostStack headers#

Add these headers to a message to use API features over SMTP. They are read as instructions and removed; the recipient never sees them. Header names are case-insensitive.

X-PostStack-Tagsstring

Comma-separated tags, e.g. welcome,onboarding. Whitespace around each tag is trimmed and empty entries are dropped. Same as the API's tags.

X-PostStack-Idempotency-Keystring

A key that makes a retry safe. If your team has already sent a message with this key, the relay answers 250 and sends nothing new. Over SMTP a repeated key is always treated as a replay, even if the message content changed — unlike the HTTP API, which answers 422 for a different payload. Same as idempotency_key.

X-PostStack-Template-Idstring

The tpl_… id of a published template. Its subject, HTML and text replace the ones in your message. An unknown id is refused with 550 Template not found, an unpublished one with 550 Template is not published. See Templates.

X-PostStack-Variablesstring (JSON object)

The template variables as one line of JSON, e.g. {"first_name":"Alice"}. JSON that does not parse is ignored without an error, and the template renders with no variables — check the rendered email if a placeholder comes out empty.

X-PostStack-Schedulestring (ISO 8601)

Deliver later instead of now, e.g. 2026-10-01T09:00:00Z. Include a timezone offset or Z. Same as scheduled_at.

await transporter.sendMail({
  from: 'Acme <hello@yourdomain.com>',
  to: 'user@example.com',
  // subject, html and text are replaced by the rendered template
  headers: {
    'X-PostStack-Template-Id': 'tpl_abc123def456ghi789',
    'X-PostStack-Variables': JSON.stringify({ first_name: 'Alice', company_name: 'Acme' }),
    'X-PostStack-Idempotency-Key': 'welcome-user-4821',
    'X-PostStack-Schedule': '2026-10-01T09:00:00Z',
  },
});

How your message is processed#

PostStack is a submission relay, not a byte-for-byte forwarder. Your message is parsed into its parts — addresses, subject, HTML and text bodies, attachments — recorded as an email you can see in the dashboard, and composed again on the way out. That is what makes tracking, templates, suppression and webhooks work over SMTP, and it has these consequences:

• Recipients. To and Cc come from the message headers. Any envelope recipient (RCPT TO) that is in neither becomes a Bcc. If the message has no To header, the envelope recipients are used. The sender is the From header, display name included.
• Your DKIM signature is replaced. If your server already signs (Mailcow, Postfix with OpenDKIM, Microsoft 365), that signature cannot survive recomposition — it covers the exact bytes. PostStack signs the outgoing message with the key it holds for your verified domain, so it still leaves with a valid d=yourdomain.com signature that aligns for DMARC. There is no passthrough mode.
• Only some headers are carried. Headers starting with X- (other than the PostStack ones) are passed through, and In-Reply-To and References are kept so replies thread. A very long References chain is trimmed to 1,024 characters, keeping the first id and the most recent ones. Every other header is dropped, and PostStack sets its own Message-ID and Date.
• Tracking changes your HTML. Open tracking adds a pixel and click tracking rewrites links. Both are on by default and can be turned off per domain — see Tracking.
• Inline images stay inline. Parts referenced from the HTML with cid: are kept as inline attachments, not converted to data: URIs (which Gmail and Outlook strip).
• No mailbox signature. A mailbox signature set in PostStack is never added to SMTP submissions, because your mail client has already added its own.

Limits#

Attachments are counted after decoding, so a 10 MB file is 10 MB here even though it is about 13.5 MB inside the message. API-key sends have no per-connection rate limit beyond your plan quota.

Replies and error codes#

Authentication is checked at AUTH; everything else — sender domain, template, quota, suppression — is checked once the whole message has arrived, and the answer is the reply to the final . of DATA. A 5xx is permanent: fix the message rather than retrying. A 4xx is temporary and a mail server will retry it on its own.

Mailbox credentials#

When the password is not an API key, the relay treats the username as a mailbox address and checks the mailbox password. This is what a desktop or phone mail client uses. Compared with an API key:

• The username must be the full address, e.g. anna@yourdomain.com, and the mailbox must be active.
• The From address must be exactly that mailbox; anything else gets 550 From address must be anna@yourdomain.com.
• A copy of each sent message is saved to the mailbox's Sent folder.
• Sending is limited to 60 messages per hour per mailbox.
• Sends are always live — there is no test mode for mailbox credentials.

Test the connection#

To separate a network or credentials problem from a problem in your application, send one message from a terminal with swaks:

swaks --server smtp.poststack.dev --port 587 --tls \
  --auth PLAIN --auth-user poststack --auth-password "$POSTSTACK_API_KEY" \
  --from hello@yourdomain.com --to you@example.com \
  --header "Subject: PostStack SMTP test"

Or inspect the TLS handshake and capabilities without sending:

# See the certificate and the server's capabilities without sending anything.
openssl s_client -connect smtp.poststack.dev:587 -starttls smtp -quiet
# then type:  EHLO test.example   →   250-AUTH PLAIN LOGIN … 250 SIZE 37748736
#             QUIT

Troubleshooting#

Next steps