API Documentation

curl -X POST https://mailboxkit.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "owner_email": "human-owner@example.com"}'

{
  "api_key": "mbk_xxxxxxxxxx...",
  "email": "abc123@agent.mailboxkit.com",
  "inbox_id": "01JXYZ...",
  "owner_email": "human-owner@example.com",
  "message": "Save your API key — it will not be shown again."
}

Authorization: Bearer mbk_your_api_key

npm install mailboxkit

import MailboxKit from "mailboxkit";

// Reads MAILBOXKIT_API_KEY from env automatically
const mbk = new MailboxKit();

// Or pass the key explicitly
const mbk = new MailboxKit({ apiKey: "mbk_your_api_key" });

// Send an email
const msg = await mbk.send(inboxId, {
  to: ["recipient@example.com"],
  subject: "Hello from the SDK",
  html: "<p>Sent with the Node.js SDK</p>",
});

// Reply to a message
await mbk.reply(inboxId, msg.id, {
  text: "Thanks for your reply!",
});

// Wait for a matching email (polls until found or timeout)
const received = await mbk.waitFor(inboxId, {
  from: "sender@example.com",
  subject: /order confirmation/i,
  timeout: 30_000,
});

// Register a new organization
const reg = await mbk.register({
  name: "My Agent",
  owner_email: "owner@company.com",
});

{
  "mcpServers": {
    "mailboxkit": {
      "command": "npx",
      "args": ["-y", "mailboxkit-mcp"],
      "env": {
        "MAILBOXKIT_API_KEY": "mbk_your_api_key",
        "MAILBOXKIT_INBOX_ID": "your_default_inbox_id"
      }
    }
  }
}

{
  "event": "message.received",
  "timestamp": "2026-02-20T12:00:00Z",
  "data": {
    "id": 42,
    "inbox_id": 1,
    "message_id": "<abc123@example.com>",
    "from_email": "sender@example.com",
    "to_emails": ["inbox@yourdomain.com"],
    "subject": "Re: Order #1234",
    "text_body": "Thanks, got it!",
    "html_body": "<p>Thanks, got it!</p>",
    "attachments": [
      {
        "id": 1,
        "filename": "receipt.pdf",
        "mime_type": "application/pdf",
        "size": 24580,
        "url": "https://r2.mailboxkit.com/attachments/..."
      }
    ],
    "thread_id": 5,
    "created_at": "2026-02-20T12:00:00Z"
  }
}

import hmac, hashlib

def verify_signature(payload_bytes, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your webhook handler:
signature = request.headers["X-MailboxKit-Signature"]
is_valid = verify_signature(request.body, signature, WEBHOOK_SECRET)

const crypto = require("crypto");

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// In your webhook handler:
const signature = req.headers["x-mailboxkit-signature"];
const isValid = verifySignature(req.rawBody, signature, WEBHOOK_SECRET);

curl -X POST https://mailboxkit.com/api/v1/api_keys \
  -H "Authorization: Bearer mbk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Key", "test": true}'

curl -X POST https://mailboxkit.com/api/v1/inboxes/{inbox_id}/messages/send \
  -H "Authorization: Bearer mbk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-abc123" \
  -d '{
    "to": ["recipient@example.com"],
    "subject": "Order confirmation",
    "text": "Your order has been confirmed."
  }'

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1708430400

{
  "error": "insufficient_balance",
  "message": "Your organization does not have enough credit to send this email.",
  "action": "Top up your wallet to continue sending.",
  "billing_url": "https://mailboxkit.com/billing",
  "docs_url": "https://mailboxkit.com/api-docs#billing-errors",
  "balance_mills": 0,
  "balance_dollars": "$0.000",
  "cost_mills": 2,
  "cost_dollars": "$0.002",
  "emails_remaining": 0
}

import MailboxKit from "mailboxkit";

const mbk = new MailboxKit(); // reads MAILBOXKIT_API_KEY from env

// Send an email
const message = await mbk.send(inboxId, {
  to: ["customer@example.com"],
  subject: "Your order has shipped",
  html: "<p>Your package is on the way!</p>",
});
console.log("Sent:", message.id);

// Wait for a reply (polls with timeout)
const reply = await mbk.waitFor(inboxId, {
  subject: /re: your order/i,
  timeout: 60_000,
});
console.log("Got reply:", reply.extracted_text);

// Reply back
await mbk.reply(inboxId, reply.id, {
  text: "Thanks for confirming!",
});

// Add to your MCP client settings (e.g. .mcp.json)
{
  "mcpServers": {
    "mailboxkit": {
      "command": "npx",
      "args": ["-y", "mailboxkit-mcp"],
      "env": {
        "MAILBOXKIT_API_KEY": "mbk_your_api_key",
        "MAILBOXKIT_INBOX_ID": "your_default_inbox_id"
      }
    }
  }
}

// Then ask your AI assistant:
// "Send an email to bob@example.com about the meeting tomorrow"
// "Check my inbox for new messages"
// "Reply to the latest email from alice@example.com"

{
  "type": "function",
  "function": {
    "name": "send_email",
    "description": "Send an email via MailboxKit",
    "parameters": {
      "type": "object",
      "properties": {
        "to": { "type": "string", "description": "Recipient email address" },
        "subject": { "type": "string", "description": "Email subject" },
        "body": { "type": "string", "description": "Email body (HTML)" }
      },
      "required": ["to", "subject", "body"]
    }
  }
}

import requests

MAILBOXKIT_API_KEY = "mbk_your_api_key"
INBOX_ID = 1

def send_email(to, subject, body):
    response = requests.post(
        f"https://mailboxkit.com/api/v1/inboxes/{INBOX_ID}/messages/send",
        headers={
            "Authorization": f"Bearer {MAILBOXKIT_API_KEY}",
            "Content-Type": "application/json",
        },
        json={"to": [to], "subject": subject, "html": body},
    )
    return response.json()

from langchain.tools import tool
import requests

MAILBOXKIT_API_KEY = "mbk_your_api_key"
INBOX_ID = 1

@tool
def send_email(to: str, subject: str, body: str) -> str:
    """Send an email to a recipient via MailboxKit."""
    response = requests.post(
        f"https://mailboxkit.com/api/v1/inboxes/{INBOX_ID}/messages/send",
        headers={
            "Authorization": f"Bearer {MAILBOXKIT_API_KEY}",
            "Content-Type": "application/json",
        },
        json={"to": [to], "subject": subject, "html": body},
    )
    data = response.json()
    return f"Email sent (ID: {data['data']['id']})"

from crewai import Agent, Task
from langchain.tools import tool
import requests

MAILBOXKIT_API_KEY = "mbk_your_api_key"
INBOX_ID = 1

@tool
def send_email(to: str, subject: str, body: str) -> str:
    """Send an email to a recipient."""
    response = requests.post(
        f"https://mailboxkit.com/api/v1/inboxes/{INBOX_ID}/messages/send",
        headers={
            "Authorization": f"Bearer {MAILBOXKIT_API_KEY}",
            "Content-Type": "application/json",
        },
        json={"to": [to], "subject": subject, "html": body},
    )
    return response.json()

@tool
def check_inbox() -> str:
    """Check for new emails in the inbox."""
    response = requests.get(
        f"https://mailboxkit.com/api/v1/inboxes/{INBOX_ID}/messages",
        headers={"Authorization": f"Bearer {MAILBOXKIT_API_KEY}"},
    )
    messages = response.json()["data"]
    return f"Found {len(messages)} messages"

support_agent = Agent(
    role="Customer Support Agent",
    goal="Handle customer emails professionally",
    tools=[send_email, check_inbox],
)

---
name: mailboxkit
description: Send and receive emails via MailboxKit API
requires:
  env:
    - MAILBOXKIT_API_KEY
    - MAILBOXKIT_INBOX_ID
  bins:
    - curl
    - jq
---

# MailboxKit Email Skill

You can send and check emails using the MailboxKit API.

## Send an email

When the user asks you to send an email, use:

```bash
curl -s -X POST "https://mailboxkit.com/api/v1/inboxes/$MAILBOXKIT_INBOX_ID/messages/send" \
  -H "Authorization: Bearer $MAILBOXKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["RECIPIENT"],
    "subject": "SUBJECT",
    "html": "BODY"
  }' | jq .
```

Replace RECIPIENT, SUBJECT, and BODY with the values from the conversation.

## Check inbox for new messages

```bash
curl -s "https://mailboxkit.com/api/v1/inboxes/$MAILBOXKIT_INBOX_ID/messages" \
  -H "Authorization: Bearer $MAILBOXKIT_API_KEY" | jq '.data[:5]'
```

## Reply to a message

When replying to a specific message (you'll need the message ID):

```bash
curl -s -X POST "https://mailboxkit.com/api/v1/inboxes/$MAILBOXKIT_INBOX_ID/messages/MESSAGE_ID/reply" \
  -H "Authorization: Bearer $MAILBOXKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "REPLY_BODY",
    "html": "<p>REPLY_BODY</p>"
  }' | jq .
```

## Search messages

```bash
curl -s -X POST "https://mailboxkit.com/api/v1/messages/search" \
  -H "Authorization: Bearer $MAILBOXKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SEARCH_TERM"}' | jq '.data[:5]'
```