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:

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:

Response
{
  "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
npm install @mailpipe/sdk

MCP Server

@mailpipe/mcp-server
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.

Use with AI

Connect Claude or other AI assistants to your email using our MCP server.

Set up MCP Server

Need Help?

Having trouble with the API? Our support team is here to help.

Contact Support