Secure your API access

Authentication

All Mailpipe API requests must be authenticated using an API key. This guide covers key formats, how to generate keys from your dashboard, available scopes, and security best practices.

API Keys

Mailpipe uses API keys to authenticate requests. Every key is prefixed to indicate whether it targets the live environment or the test environment:

Live Key

mp_live_xxxxxxxxxxxxxxxxxx

Affects real data. Use in production server-side code only.

Test Key

mp_test_xxxxxxxxxxxxxxxxxx

Safe for development. Requests are sandboxed and do not send real email.

Generating an API Key

Open your Dashboard → Settings → API Keys
Click Create New Key
Enter a descriptive name (e.g., production-backend)
Select the permission scopes your application needs
Click Create and copy the key immediately — it is shown only once

The full key value is displayed only at creation time. Store it securely in a password manager or secrets manager before closing the dialog.

Bearer Authentication

Pass your API key as a Bearer token in the Authorization header on every request. No other authentication schemes are supported.

HTTP Header

Authorization: Bearer mp_live_your-api-key-here

Full example using curl:

cURL

curl -X GET "https://api.mailpipe.dev/v1/mailboxes" \
  -H "Authorization: Bearer mp_live_your-api-key-here" \
  -H "Content-Type: application/json"

The same request using the official Node.js SDK:

Node.js

import { MailpipeClient } from '@mailpipe/sdk';

const client = new MailpipeClient({
  apiKey: process.env.MAILPIPE_API_KEY, // mp_live_...
});

const mailboxes = await client.mailboxes.list();
console.log(mailboxes.data);

Requests made without a valid key will receive a 401 Unauthorized response. Requests made with a key that lacks the required scope will receive 403 Forbidden.

Key Scopes

Scopes limit what an API key is permitted to do. Assign only the scopes your application actually needs — following the principle of least privilege reduces the impact of a compromised key.

Scope	Description
`mail:send`	Send outbound email messages
`mail:read`	Read messages, threads, and attachments
`mail:write`	Modify messages (mark read, star, move, delete)
`domains:read`	List domains and inspect DNS record status
`domains:write`	Add, verify, and remove domains
`mailboxes:read`	List mailboxes and view their configuration
`mailboxes:write`	Create, update, and delete mailboxes
`webhooks:read`	List configured webhook endpoints
`webhooks:write`	Create and delete webhook endpoints

A key with no scopes can authenticate but cannot access any resources. You must grant at least one scope when creating a key.

Key Rotation

Rotate API keys regularly to limit the window of exposure if a key is ever leaked. The recommended rotation period is every 90 days for production keys.

Safe Rotation Procedure

Generate a new API key with the same scopes as the key you are replacing
Update your environment variable or secrets manager with the new key
Deploy your updated application and verify it is using the new key
Revoke the old key from Settings → API Keys

Example: Revoking a key via the API

curl -X DELETE "https://api.mailpipe.dev/v1/keys/key_abc123" \
  -H "Authorization: Bearer mp_live_your-api-key-here"

Revoking a key is immediate. Any in-flight requests using that key will fail with401 Unauthorized once the revocation propagates (typically within a few seconds).

Security Best Practices

Never hard-code keys

Do not embed API keys directly in source code. Anyone with access to your repository or compiled binary can extract them.

Use environment variables

Store keys in environment variables and load them at runtime. Use a secrets manager (AWS Secrets Manager, Doppler, Infisical) for production workloads.

Never expose keys client-side

API keys must only be used from server-side code. Never ship them in browser bundles, mobile apps, or any code that runs on a device you do not control.

Restrict scopes

Create separate keys per service, each with only the scopes it needs. A key used solely to send email should have mail:send only.

Monitor usage

Review the usage dashboard regularly. Unexpected spikes in API calls can indicate a compromised key. Set up alerts when available.

Loading keys from environment variables

.env (never commit this file)

MAILPIPE_API_KEY=mp_live_your-api-key-here

Node.js

// Use process.env — the key is never in source code
const client = new MailpipeClient({
  apiKey: process.env.MAILPIPE_API_KEY,
});

Python

import os
from mailpipe import MailpipeClient

client = MailpipeClient(api_key=os.environ["MAILPIPE_API_KEY"])

Still have questions?

We can help with anything from setup to scaling.

Contact support