Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Postmark to Fondoo

mailLive6 min readUpdated

This guide sets Postmark as the delivery service for the email your Fondoo site sends. Fondoo still decides who may receive each message, checks consent and suppressions, and keeps the delivery log. Postmark only carries the mail, using one message stream that you choose. Your AI agent keeps using the normal Fondoo email operations, such as sendemail.

What Fondoo can do with it

  • Send transactional and marketing email for a site through one Postmark server and message stream.
  • Use Postmark for one site only, or as the default for the whole workspace. A site setting overrides the workspace setting.
  • Receive delivery, bounce, spam complaint, open and click events from Postmark by webhook. Hard bounces and complaints add the address to your suppression list.

Approvals and limits that still apply:

  • configure_email_provider and set_provider need the workspace owner.
  • Marketing email needs evidenced consent and a postal address set with update_email_settings.
  • An agent that sends more than 1,000 marketing emails for a site in a month needs your approval.
  • Each send_email call takes up to 100 recipients.

Before you start

  • A Postmark account. New accounts start on a free Developer plan with a small monthly allowance. Paid plans add volume (pricing). Postmark bills you directly. Fondoo's per-site email overage charge does not apply to mail sent through your own provider.
  • Account approval. Until Postmark approves your account, you can only send to addresses on domains you have verified. Only the Account Owner can request approval (approval process).
  • A verified domain in Postmark (DKIM, and ideally a custom Return-Path).
  • The same domain added and verified on your Fondoo site (set_custom_domain, then get_domain_status until it is active). Fondoo matches the From domain exactly.
  • One message stream for Fondoo to use. Fondoo sends everything through the stream you configure. Postmark keeps transactional mail (default stream ID outbound) separate from broadcast (bulk) mail. If you will send newsletters or other marketing through Fondoo, check Postmark's stream rules before you choose.

Step by step: get your credentials

  1. Verify your domain. In Postmark open Sender Signatures, find your domain and click DNS Settings (or Add a DKIM DNS record). Add the DKIM TXT record at your DNS host. Add the Return-Path CNAME too (hostname pm_bounces, value pm.mtasv.net by default). Click Verify to check (verify a domain).
  2. Open Servers and pick the server Fondoo should send through, or create one.
  3. Open the server's API Tokens tab and copy a Server API token (server vs account tokens). Do not use the Account API token. Fondoo sends with the X-Postmark-Server-Token header, which needs a server token. A server can have up to 3 tokens.
  4. Note the message stream ID you want to use, for example outbound for the default transactional stream. The ID is shown in the server's message stream settings.
  5. Write down your sending domains in lowercase, for example example.com.

You now have:

Fondoo credential fieldWhat to put in it
apiKey (required)The Server API token
stream (required)The message stream ID, for example outbound
domains (required in practice)List of verified sending domains, lowercase
webhookUsername, webhookPassword (optional)Basic auth pair you choose for webhooks

Connect it in Fondoo

In the dashboard. The Connections page lists an Email card, but it only opens setup instructions. There is no form for Postmark tokens yet. Use your agent or the REST API.

By asking your agent. Example prompt:

Use Postmark for my site's email. I will save the token myself. Then set up example.com as the sending domain and check it.

configure_email_provider takes the token directly in its input and has no secure paste page. Anything pasted into a chat can stay in chat logs, so run that call yourself over REST with an owner API key. Let the agent do the rest.

The calls, in order:

  1. configure_email_provider({siteId, provider:"postmark", credential:{apiKey:"...", stream:"outbound", domains:["example.com"]}}). Leave out siteId to make it the workspace default.
  2. set_provider({siteId, capability:"email", provider:"postmark"}).
  3. setup_sending_domain({siteId, domain:"example.com"}). Postmark owns the DNS records, so Fondoo returns none. It checks that the domain is in your domains list.
  4. check_sending_domain({siteId, domain:"example.com"}).

connect_service({provider:"postmark", siteId}) returns a signed 15-minute link with setup instructions. It never takes credentials.

REST equivalent:

curl -X POST https://api.getfondoo.com/v1/ops/configure_email_provider \
  -H "Authorization: Bearer $FONDOO_OWNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"YOUR-SITE-ID","provider":"postmark","credential":{"apiKey":"'"$POSTMARK_SERVER_TOKEN"'","stream":"outbound","domains":["example.com"]}}'

Webhooks

Webhooks tell Fondoo about bounces and complaints so it can stop mailing bad addresses.

  1. Pick a long random username and password for the webhook. Run configure_email_provider again with the same scope and the full credential, now including webhookUsername and webhookPassword. Keeping the same scope keeps the same connection ID.
  2. Run get_email_provider({siteId}) and copy feedbackUrl. It looks like https://<fondoo email origin>/webhooks/email/postmark/<providerId>.
  3. In Postmark open the server, choose the same message stream, open Webhooks and click Add webhook (how webhooks work).
  4. Enter the URL. Add your username and password as basic HTTP auth credentials, either in the form's auth fields or in the URL as https://username:password@host/path (webhooks overview).
  5. Tick Delivery, Bounce, Spam complaint, Open and Click. Fondoo ignores other types.

How it is secured: Postmark does not sign webhooks with HMAC. Fondoo compares the Authorization: Basic header with your stored username and password in constant time, and rejects anything that does not match. A bounce counts as hard when Postmark's Type is HardBounce.

Test that it works

  1. get_email_provider({siteId}) should show provider: "postmark".
  2. check_sending_domain({siteId, domain}) should return verified: true.
  3. Add yourself as a contact (create_contact) and send a transactional message with send_email({..., category:"transactional"}). Before approval, use an address on your own verified domain, or Postmark's test sink: the address test at Postmark's blackhole domain (blackhole.postmarkapp.com).
  4. Check list_emails({siteId}), and the stream's Activity in Postmark.

Troubleshooting

  • "Postmark send failed" in the delivery log: common causes are an Account token instead of a Server token, a wrong stream ID, an unconfirmed sender (Postmark answers HTTP 422), or an unapproved account sending outside your domains.
  • "Sender domain is not configured": the From domain is missing from domains, or is spelled differently. Re-run configure_email_provider with the exact lowercase domain.
  • "Verify domain ownership before configuring email.": finish verifying the domain on your Fondoo site first.
  • "From must use the site's authenticated domain or the shared sending domain": check_sending_domain has not marked the domain verified. With Postmark, Fondoo has no DNS records of its own to check, so this check may not pass in the current release. This may differ for your account. If it stays false, contact Fondoo support.
  • Webhook returns 403: the basic auth pair in Postmark does not match the one saved in Fondoo, or the webhook is on a different stream or server. Use Postmark's Verify webhook button after fixing it.
  • Marketing mail flagged by Postmark: you are sending broadcasts on a transactional stream. Fondoo sends all of a site's mail through the one stream you configured, so it cannot split transactional and marketing mail between streams. Ask Postmark which stream fits your mix, or keep newsletters on another provider.

Limits, data and security

  • Fondoo sends through a Postmark connection at up to one message per second. Postmark's own limits are listed in its API docs.
  • Fondoo stores the credential (token, stream, domains, webhook auth pair) encrypted, bound to the connection. It is never returned by any operation.
  • Fondoo keeps delivery records and suppression entries. From webhooks it reads only the record type, message ID, recipient and bounce type.
  • To rotate: create a new Server API token, run configure_email_provider with it, test, then delete the old token in Postmark.
  • To disconnect: set_provider({siteId, capability:"email", provider:"builtin"}), then remove the token and webhook in Postmark.