Mailpipe logo
MailpipeDocs

API Reference

REST API documentation

The Mailpipe API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Base URL

All API requests should be made to the following base URL:

code
https://api.mailpipe.dev/v1

All API endpoints are served over HTTPS. Unencrypted HTTP requests will be rejected.

Authentication

Authenticate your API requests by including your API key in the Authorization header:

Request Header
Authorization: Bearer mp_live_your-api-key-here

Keep your API keys secure

Your API keys carry many privileges. Do not share them in publicly accessible areas such as GitHub, client-side code, etc.
Get your API key

Response Codes

CodeDescription
200OK — Request succeeded
201Created — Resource successfully created
400Bad Request — Invalid parameters
401Unauthorized — Invalid or missing API key
403Forbidden — Insufficient permissions
404Not Found — Resource does not exist
429Too Many Requests — Rate limit exceeded
500Internal Server Error — Something went wrong

Endpoints

Messages

Read, search, and manage email messages

GET/v1/messages
GET/v1/messages/:id
POST/v1/messages
PATCH/v1/messages/:id
DELETE/v1/messages/:id

Threads

View email conversations grouped by thread

GET/v1/threads
GET/v1/threads/:id

Mailboxes

Manage email addresses and mailbox settings

GET/v1/mailboxes
POST/v1/mailboxes
GET/v1/mailboxes/:id
PATCH/v1/mailboxes/:id
DELETE/v1/mailboxes/:id

Domains

Configure and verify your email domains

GET/v1/domains
POST/v1/domains
GET/v1/domains/:id
POST/v1/domains/:id/verify
DELETE/v1/domains/:id

API Keys

Manage API keys and permissions

GET/v1/keys
POST/v1/keys
DELETE/v1/keys/:id

Usage

Monitor API usage and quotas

GET/v1/usage

User

Current user information

GET/v1/me

Example Request

Here's an example of listing messages using cURL:

cURL
curl -X GET "https://api.mailpipe.dev/v1/messages?limit=10&unread=true" \
  -H "Authorization: Bearer mp_live_your-api-key-here" \
  -H "Content-Type: application/json"

Example response:

200 OK
{
  "data": [
    {
      "id": "msg_123abc",
      "mailbox_id": "mbx_456def",
      "from": "sender@example.com",
      "to": ["you@yourdomain.com"],
      "subject": "Hello World",
      "snippet": "This is a preview of the email content...",
      "is_read": false,
      "is_starred": false,
      "received_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

SDKs & Libraries

Node.js SDK

@mailpipe/sdk
Install
npm install @mailpipe/sdk

MCP Server

@mailpipe/mcp-server
Install
npm install @mailpipe/mcp-server
Learn more about the MCP Server

Rate Limits

API requests are rate limited to ensure fair usage. The default limits are:

  • 1,000 requests per minute for read operations (GET)
  • 100 requests per minute for write operations (POST, PATCH, DELETE)
  • 50 emails per hour for sending

Rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Still have questions?

Our team is here to help with anything from setup to scaling.

Contact support