Configuration

Set up your Mailpipe environment

Configure your domains, email providers, environment variables, and mailboxes to get Mailpipe working end-to-end in your infrastructure.

Domain Setup

Before you can send or receive email through Mailpipe you must add and verify at least one domain. Verification proves that you own the domain and authorises Mailpipe to handle mail on its behalf.

Adding a domain

Go to Settings → Domains in your dashboard
Click Add Domain and enter your domain name (e.g., example.com)
Add the DNS records shown in the next step to your domain registrar or DNS provider
Click Verify once the records have propagated

Required DNS records

Add all three record types to enable inbound delivery, outbound authentication, and anti-spoofing protection.

MX — Inbound delivery

Type:     MX
Host:     @ (root domain) or your subdomain
Priority: 10
Value:    mx.mailpipe.dev

TXT — SPF (outbound sender policy)

Type:  TXT
Host:  @
Value: v=spf1 include:spf.mailpipe.dev ~all

CNAME — DKIM (cryptographic signing)

Type:  CNAME
Host:  mailpipe._domainkey
Value: mailpipe._domainkey.mailpipe.dev

DNS propagation typically completes within minutes but can take up to 48 hours depending on your provider's TTL settings. Mailpipe checks verification status automatically every few minutes once you've initiated it.

Provider Configuration

Mailpipe routes outbound email through your chosen transactional email provider. Connecting your own provider account gives you full control over deliverability, sending quotas, and billing. Supported providers are listed below.

Resend

RESEND_API_KEY

Recommended for new projects

Postmark

POSTMARK_API_KEY

Excellent deliverability

SendGrid

SENDGRID_API_KEY

High-volume sending

Mailgun

MAILGUN_API_KEY

Flexible routing rules

Connecting a provider

Obtain an API key from your chosen provider's dashboard
Go to Settings → Providers
Select your provider and paste in the API key
Click Save & Test — Mailpipe will send a test message to confirm connectivity

You can also supply provider credentials via environment variables (see the next section) for infrastructure-as-code and CI/CD workflows.

Environment Variables

All Mailpipe configuration can be driven through environment variables. Copy the template below into a .env.local file for local development, and configure the same variables in your hosting provider's secrets management for production.

.env.local

# ── Mailpipe ──────────────────────────────────────────────────
# Your Mailpipe API key (generate from Settings → API Keys)
MAILPIPE_API_KEY=mp_live_your-api-key-here

# Organisation ID (found in Settings → General)
MAILPIPE_ORG_ID=org_xxxxxxxxxxxxxxxx

# ── Email Providers (set whichever you use) ───────────────────
RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
POSTMARK_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MAILGUN_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx-xxxxxxxx
MAILGUN_DOMAIN=mg.yourdomain.com

# ── Supabase (if using Supabase integration) ──────────────────
NEXT_PUBLIC_SUPABASE_URL=https://xxxxxxxxxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# ── Webhooks ──────────────────────────────────────────────────
# Secret used to verify incoming webhook signatures
MAILPIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Never commit secrets to version control

Add .env.local and .env to your .gitignore. Use a secrets manager for production deployments.

Variable reference

Variable	Required	Description
`MAILPIPE_API_KEY`	Required	Authenticates all API requests
`MAILPIPE_ORG_ID`	Required	Scopes requests to your organisation
`RESEND_API_KEY`	Optional	Provider key for Resend
`POSTMARK_API_KEY`	Optional	Provider key for Postmark
`SENDGRID_API_KEY`	Optional	Provider key for SendGrid
`MAILGUN_API_KEY`	Optional	Provider key for Mailgun
`MAILGUN_DOMAIN`	Optional	Sending domain for Mailgun
`MAILPIPE_WEBHOOK_SECRET`	Optional	Verifies webhook request signatures

Mailbox Configuration

A mailbox is an email address tied to one of your verified domains. Messages sent to that address are stored in Mailpipe and optionally forwarded to webhooks or other email providers.

Creating a mailbox

Open the Inbox section of your dashboard
Click + New Mailbox
Enter the local part of the address (e.g., support)
Choose a verified domain from the dropdown
Optionally enable webhook delivery or provider forwarding
Click Create Mailbox

Create mailbox via API

curl -X POST "https://api.mailpipe.dev/v1/mailboxes" \
  -H "Authorization: Bearer mp_live_your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "support",
    "domain_id": "dom_xxxxxxxxxxxxxxxx",
    "display_name": "Support Team",
    "forward_to_webhook": true
  }'

Setting up aliases

Aliases let multiple addresses deliver into the same mailbox. For example, bothhelp@example.com andinfo@example.com can route to yoursupport@example.com mailbox.

Add an alias via API

curl -X POST "https://api.mailpipe.dev/v1/mailboxes/mbx_123/aliases" \
  -H "Authorization: Bearer mp_live_your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "help",
    "domain_id": "dom_xxxxxxxxxxxxxxxx"
  }'

Aliases can also be managed from the mailbox settings panel in the dashboard. There is no limit on the number of aliases per mailbox.

Need Help?

Our team is here to help. Reach out if you have any questions.

Contact Support