Building a transactional email service

Transactional email — receipts, password resets, confirmations, alerts — is sent one message at a time in response to something a user did. It needs to be fast and reliable, and it should be kept separate from your marketing mail. Here's how to build it on BlacklistGuard.

Set up

• Verify a sending domain and publish SPF, DKIM, and DMARC — see Set up a sending domain. Your from_email must be on a verified domain.
• Create an API key for your backend service and keep it server-side — see Authentication.

Keep it separate from marketing

Transactional mail (which users expect and engage with) and marketing mail (which has complaints and unsubscribes) build very different reputations. Don't let your marketing reputation drag down your password resets. A common pattern is to send transactional mail from a dedicated subdomain — e.g. mail.yourdomain.com for transactional and news.yourdomain.com for marketing — so each builds its own reputation.

Sending a message

Each message is a single POST to the send endpoint:

curl -X POST https://app.blacklistguard.com/api/v1/emails/send \
  -H "X-API-Key: efk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_email": "noreply@mail.yourdomain.com",
    "from_name": "Acme",
    "to": "user@example.com",
    "subject": "Reset your password",
    "body": "<p>Click the link to reset your password…</p>"
  }'

Handle the response

A success returns 201 with { "data": { "status": "queued", "id": "…" } }. Store the id so you can look the message up later in Messages. On failure, the envelope has "success": false with an error and a code — handle at least these:

• VALIDATION_ERROR — a bad request or an unverified from_email. Fix and retry.
• RATE_LIMIT_EXCEEDED — you're sending too fast; back off briefly and retry.
• INSUFFICIENT_BALANCE / PLAN_LIMIT_REACHED — top up or upgrade.

See the full error codes. Build a short retry with backoff for transient errors (429, 500), but don't retry validation errors.

Respect suppression

Even transactional senders bounce and get complaints. Hard bounces are suppressed automatically, so you won't keep hammering dead addresses; set up feedback loops to catch complaints too. If a critical message (like a password reset) doesn't send, check whether the address is on a suppression list — that's usually why.

Monitor

Watch delivery and bounces like any other stream — see Tracking delivery, bounces & complaints. Because users expect transactional mail, a rising bounce or deferral rate here is an early warning worth acting on quickly.