MailPi Developer Platform v1.0

MailPi Developer Documentation

Dispatch high-deliverability transactional emails, schedule future broadcasts, isolate client workspaces, and verify cryptographically signed webhook event streams with our official SDKs.

Quickstart: Send an Email

Use your API key from the Console to send your first email:

index.ts

import { MailPi } from "@mailpi/node";

const mailpi = new MailPi(process.env.MAILPI_API_KEY);

const { data, error } = await mailpi.emails.send({
  from: "notifications@yourdomain.com",
  to: ["user@example.com"],
  subject: "Welcome to our startup!",
  html: "<p>Hello from MailPi TypeScript SDK!</p>",
});

if (error) {
  console.error("Dispatch error:", error);
} else {
  console.log("Sent successfully, message ID:", data?.id);
}

MailPi Developer CLI (`mailpi`)

v1.0.0

The official MailPi CLI provides a fast command-line workflow to authenticate, test email rendering in the terminal, view virtual sandboxes, and inspect live AWS SES quota consumption without opening the web console.

Node.js / npm Package

Run instantly via npx with zero installation or install globally:

npx @mailpi/cli --help

Python Package

Included automatically when installing the official Python client:

pip install mailpi && mailpi --help

API Keys & Environments

MailPi distinguishes between production email dispatches and development testing via distinct API key prefixes:

Live Environmentmp_live_...

Dispatches real emails to external mailboxes with 2048-bit DKIM, SPF, and DMARC alignment.

Sandbox Environmentmp_test_...

Simulates delivery with 0 SES quota consumption. Captured directly into your dashboard virtual test inbox.

Virtual Sandbox Mode

Develop and run automated CI/CD test suites without burning your sending limits or sending spam to test emails. Initialize with a mp_test_... key or switch the dashboard environment toggle to Sandbox.

View simulated emails in the virtual inbox:Open Sandbox Inbox

Node.js & TypeScript SDK (`@mailpi/node`)

npm install @mailpi/node

Features built-in TypeScript definitions, retry logic, scheduled sending, and cryptographic webhook verification helpers.

Python SDK (`mailpi`)

pip install mailpi

Lightweight standard-library-based client with zero third-party runtime dependencies, supporting Python 3.8 through 3.14+.

Scheduled Email Sending

Pass an ISO 8601 string in the scheduled_at parameter to queue emails for future dispatch up to 30 days in advance:

// Schedule for 24 hours from now await mailpi.emails.send({ from: "reminders@yourdomain.com", to: "user@domain.com", subject: "Your demo starts in 1 hour", html: "<p>Here is your join link...</p>", scheduled_at: "2026-09-04T15:00:00Z" });

Idempotency Keys & Safe Retries

Pass the Idempotency-Key header to prevent duplicate email dispatches during connection drops or automated worker retries:

await mailpi.emails.send({ from: "billing@yourdomain.com", to: "buyer@domain.com", subject: "Invoice Paid", html: "<p>Receipt attached.</p>", idempotencyKey: "payment-checkout-session-cs_live_981240" });

Cryptographically Signed Webhooks

Every webhook HTTP POST callback contains the X-MailPi-Signature: t=timestamp,v1=signature header signed using HMAC-SHA256 with your endpoint secret (whsec_...).

// Express.js verification with @mailpi/node import { MailPi } from "@mailpi/node"; const mailpi = new MailPi(process.env.MAILPI_API_KEY); app.post("/webhooks/mailpi", express.raw({ type: "application/json" }), (req, res) => { const isValid = mailpi.webhooks.verifySignature({ payload: req.body.toString("utf-8"), signature: req.headers["x-mailpi-signature"], secret: process.env.MAILPI_WEBHOOK_SECRET // whsec_... }); if (!isValid) return res.status(400).send("Invalid signature"); res.status(200).send("OK"); });

Agency Sub-Accounts & Client Workspaces

Isolate client sender reputations, API keys, and monthly quotas. Send on behalf of any child sub-account by including the X-Subaccount-Id header:

curl -X POST https://api.mailpi.dev/v1/emails \ -H "Authorization: Bearer mp_live_master_key" \ -H "X-Subaccount-Id: 2035588e-ba33-4e0d-bc28-2655b1f1f93f" \ -H "Content-Type: application/json" \ -d '{"from": "client@clientdomain.com", "to": ["user@example.com"], "subject": "Hi"}'

Interactive OpenAPI 3.0 Documentation

Explore and test all endpoints directly in Swagger UI with live schemas.

Open Swagger API Docs