Postpipe

Quickstart

Send your first email in under 5 minutes

Tick each step as you go. By the end you'll have a verified domain, an API key, and a real email delivered through Postpipe.

Guided checklist

0 / 7 done

Set environment variables

The sample uses three env vars so you never paste your API key inline. Export them once per shell session — or load them from a .env file.

bash
# macOS / Linux (bash, zsh)
export POSTPIPE_API_KEY="mg_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
export POSTPIPE_FROM="hello@mg.acme.com"
export POSTPIPE_TO="you@gmail.com"
export POSTPIPE_BASE_URL="https://your-domain.com"

# Windows PowerShell
# $env:POSTPIPE_API_KEY = "mg_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
# $env:POSTPIPE_FROM    = "hello@mg.acme.com"
# $env:POSTPIPE_TO      = "you@gmail.com"
# $env:POSTPIPE_BASE_URL = "https://your-domain.com"

# .env file (loaded by dotenv / python-dotenv)
# POSTPIPE_API_KEY=mg_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
# POSTPIPE_FROM=hello@mg.acme.com
# POSTPIPE_TO=you@gmail.com

End-to-end sample send

Once the env vars above are exported, paste this into a terminal. Postpipe queues the email immediately and you'll see it appear in Logs within a second.

bash
# Send a test email — POSTPIPE_API_KEY, POSTPIPE_FROM and POSTPIPE_TO must be exported
curl -X POST $POSTPIPE_BASE_URL/api/v1/emails \
  -H "Authorization: Bearer $POSTPIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"from\": \"$POSTPIPE_FROM\",
    \"to\": \"$POSTPIPE_TO\",
    \"subject\": \"Hello from Postpipe 🚀\",
    \"html\": \"<h1>It works!</h1><p>This is my first Postpipe email.</p>\",
    \"tags\": [\"quickstart\"]
  }"

# Expected response (HTTP 200)
# { "id": "01H7X1E…", "mailgun_id": "20240601…", "message": "Email queued successfully" }

Verify your DNS records

After adding SPF, DKIM, and DMARC at your DNS provider, return to the wizard and confirm all three show a green ✓. Sending before verification often lands mail in spam.

  • SPF — authorizes Mailgun to send for your domain
  • DKIM — cryptographically signs each message
  • DMARC — tells receivers how to handle failures
Loading your domains…

Postman collection

Download a ready-to-import Postman collection covering the key endpoints (send email, list logs, list domains). Import into Postman or Insomnia, set the baseUrl and apiKey variables, and you're ready to send.

Troubleshooting FAQ

Quick fixes for the most common API responses, with pointers to logs and usage limits.

401 Unauthorized

Cause: Missing or malformed Authorization header, or API key was revoked.

Fix: Confirm the header is exactly Authorization: Bearer mg_live_… and the key starts with mg_live_. Check the key's status on the API Keys page — revoked keys always return 401.

403 Forbidden

Cause: Your API key is valid but lacks the required scope (e.g. emails:send).

Fix: Open the key in API Keys and verify it has the emails:send scope. Generate a new key with the right scopes if needed.

429 Too Many Requests

Cause: You hit the per-key monthly usage limit or burst rate limit.

Fix: Check the usage bar on the API Keys page — a banner on the dashboard appears once you cross 80%. Raise monthly_limit on the key or wait for the monthly reset.

402 Payment Required

Cause: Free-tier monthly send limit reached, or prepaid credit balance is zero.

Fix: Top up credits or upgrade the plan on the workspace billing page. Counter resets monthly.

5xx Server Error

Cause: Upstream Mailgun outage, transient network failure, or a misconfigured domain.

Fix: Re-try with exponential backoff (1s, 2s, 4s — up to 5 attempts). Check the Logs view for an error_message column — it surfaces the upstream reason. Verify the sender domain is verified in the DNS wizard.

What success looks like

  • HTTP 200 response with an id field
  • A new row appears in Logs with status queued, then sent, then delivered
  • The email arrives in your inbox (check spam if DNS just propagated)