API Reference

The Mailpipe API allows you to send emails, manage mailboxes, and integrate email functionality into your applications.

Authentication

All API requests require authentication using an API key. Include your key in the Authorization header:

curl -X GET https://api.mailpipe.dev/v1/mailboxes \
  -H "Authorization: Bearer mp_live_xxxxxxxxxxxx"

Generate API keys in your dashboard settings.

Base URL

https://api.mailpipe.dev/v1

Sending Emails

POST /emails/send

Send an email through your configured email provider.

Request Body

{
  "from": "you@yourdomain.com",
  "to": ["recipient@example.com"],
  "cc": ["cc@example.com"],       // optional
  "bcc": ["bcc@example.com"],     // optional
  "subject": "Hello from Mailpipe",
  "text": "Plain text version",   // optional if html provided
  "html": "<h1>HTML version</h1>", // optional if text provided
  "reply_to": "reply@example.com", // optional
  "headers": {                     // optional custom headers
    "X-Custom-Header": "value"
  },
  "attachments": [                 // optional
    {
      "filename": "document.pdf",
      "content": "base64-encoded-content",
      "content_type": "application/pdf"
    }
  ]
}

Response

{
  "id": "msg_xxxxxxxxxx",
  "status": "sent",
  "provider_id": "provider-message-id",
  "sent_at": "2024-12-26T12:00:00Z"
}

Mailboxes

GET /mailboxes

List all mailboxes for your account.

{
  "data": [
    {
      "id": "mbx_xxxxxxxxxx",
      "name": "Support",
      "address": "support@yourdomain.com",
      "domain_id": "dom_xxxxxxxxxx",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

POST /mailboxes

Create a new mailbox.

{
  "name": "Sales",
  "address": "sales@yourdomain.com",
  "domain_id": "dom_xxxxxxxxxx"
}

Emails

GET /emails

Retrieve emails with optional filters.

Query Parameters

• mailbox_id - Filter by mailbox
• read - Filter by read status (true/false)
• starred - Filter by starred status
• from - Filter by sender address
• since - Filter by date (ISO 8601)
• page - Page number (default: 1)
• per_page - Items per page (default: 20, max: 100)

GET /emails/:id

Retrieve a single email by ID.

{
  "id": "eml_xxxxxxxxxx",
  "mailbox_id": "mbx_xxxxxxxxxx",
  "from": {
    "email": "sender@example.com",
    "name": "Sender Name"
  },
  "to": [
    { "email": "you@yourdomain.com", "name": "You" }
  ],
  "subject": "Hello!",
  "text_body": "Plain text content",
  "html_body": "<p>HTML content</p>",
  "headers": {},
  "received_at": "2024-12-26T12:00:00Z",
  "read": false,
  "starred": false,
  "labels": ["inbox"]
}

PATCH /emails/:id

Update email properties.

{
  "read": true,
  "starred": true,
  "labels": ["important", "inbox"]
}

Routing Rules

GET /routing-rules

List all routing rules.

POST /routing-rules

Create a new routing rule.

{
  "name": "Support Tickets",
  "priority": 10,
  "conditions": {
    "type": "and",
    "rules": [
      { "field": "to", "operator": "equals", "value": "support@yourdomain.com" }
    ]
  },
  "actions": {
    "deliver_to": "mbx_xxxxxxxxxx",
    "add_labels": ["support"],
    "star": false
  },
  "enabled": true
}

Webhooks

Configure webhooks to receive real-time notifications when emails arrive or are processed.

Webhook Payload

{
  "event": "email.received",
  "timestamp": "2024-12-26T12:00:00Z",
  "data": {
    "id": "eml_xxxxxxxxxx",
    "mailbox_id": "mbx_xxxxxxxxxx",
    "from": "sender@example.com",
    "to": ["you@yourdomain.com"],
    "subject": "Hello!"
  }
}

Event Types

• email.received - New email received
• email.sent - Email sent successfully
• email.bounced - Email bounced
• email.opened - Email opened (tracking required)

Error Handling

The API uses standard HTTP status codes and returns error details in the response:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'to' field is required",
    "field": "to"
  }
}

Status Codes

• 200 - Success
• 201 - Created
• 400 - Bad request
• 401 - Unauthorized
• 404 - Not found
• 429 - Rate limited
• 500 - Server error

Rate Limits

API requests are limited to 1000 requests per minute. Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1703592000

npm install @mailpipe/sdk