Secure your API access
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.
Mailpipe uses API keys to authenticate requests. Every key is prefixed to indicate whether it targets the live environment or the test environment:
mp_live_xxxxxxxxxxxxxxxxxxAffects real data. Use in production server-side code only.
mp_test_xxxxxxxxxxxxxxxxxxSafe for development. Requests are sandboxed and do not send real email.
production-backend)The full key value is displayed only at creation time. Store it securely in a password manager or secrets manager before closing the dialog.
Pass your API key as a Bearer token in the Authorization header on every request. No other authentication schemes are supported.
Authorization: Bearer mp_live_your-api-key-here
Full example using 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:
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.
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.
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.
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).
Do not embed API keys directly in source code. Anyone with access to your repository or compiled binary can extract them.
Store keys in environment variables and load them at runtime. Use a secrets manager (AWS Secrets Manager, Doppler, Infisical) for production workloads.
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.
Create separate keys per service, each with only the scopes it needs. A key used solely to send email should have mail:send only.
Review the usage dashboard regularly. Unexpected spikes in API calls can indicate a compromised key. Set up alerts when available.
MAILPIPE_API_KEY=mp_live_your-api-key-here
// Use process.env — the key is never in source code
const client = new MailpipeClient({
apiKey: process.env.MAILPIPE_API_KEY,
});import os from mailpipe import MailpipeClient client = MailpipeClient(api_key=os.environ["MAILPIPE_API_KEY"])