REST API reference

Authorization: Bearer hm_live_your_key_here

{ "error": { "code": "INBOX_NOT_FOUND", "message": "No inbox with id "8f2c…" on this account." } }

{
  "account": { "id": "a1b2c3d4-…", "email": "founder@acme.com", "name": "Acme Inc" },
  "plan": "pro",
  "status": "active",
  "plan_ends_at": "2027-10-10T00:00:00.000Z",
  "limits": {
    "inboxes": 20, "domains": 5, "storage_gb": 10,
    "recipients_per_message": 50, "api_requests_per_minute": 120
  },
  "usage": { "inboxes": 4, "domains": 1 }
}

{
  "domains": [
    { "id": "d9e8…", "domain": "acme.com", "verified": true, "active": true, "created_at": "2026-09-01T10:00:00.000Z" }
  ]
}

{
  "inboxes": [
    {
      "id": "8f2c1e0a-…",
      "email": "support-agent@acme.com",
      "name": "Acme Support Agent",
      "domain": "acme.com",
      "created_at": "2026-10-10T09:00:00.000Z",
      "created_via": "api"
    }
  ]
}

curl -X POST https://havitomail.com/api/v1/inboxes \
  -H "Authorization: Bearer $HAVITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acme.com", "username": "support-agent", "name": "Acme Support Agent"}'

{
  "id": "8f2c1e0a-5b7d-4c11-9a3e-2d6f0b9c7e41",
  "email": "support-agent@acme.com",
  "name": "Acme Support Agent",
  "domain": "acme.com",
  "created_at": "2026-10-10T09:00:00.000Z",
  "created_via": "api",
  "credentials": {
    "username": "support-agent@acme.com",
    "password": "shown-only-once",
    "imap": { "host": "mail.havitomail.com", "port": 993, "security": "SSL/TLS" },
    "smtp": { "host": "mail.havitomail.com", "port": 465, "security": "SSL/TLS" }
  }
}

{
  "inbox": { "id": "8f2c1e0a-…", "email": "support-agent@acme.com" },
  "folder": "INBOX",
  "total": 57,
  "next_since_uid": 42,
  "messages": [
    {
      "uid": 42,
      "folder": "INBOX",
      "message_id": "<CAF3x9k2@mail.example.com>",
      "in_reply_to": null,
      "references": [],
      "from": { "name": "Sam Lee", "address": "sam@example.com" },
      "to": [{ "name": "", "address": "support-agent@acme.com" }],
      "cc": [],
      "reply_to": [],
      "subject": "Where is my refund?",
      "date": "2026-10-10T09:14:03.000Z",
      "seen": false,
      "starred": false,
      "answered": false,
      "text": "Hi, I returned the jacket last week…",
      "attachments": [{ "part_id": "2", "filename": "receipt.pdf", "content_type": "application/pdf", "size": 48213 }]
    }
  ]
}

curl -X POST https://havitomail.com/api/v1/inboxes/$INBOX_ID/messages \
  -H "Authorization: Bearer $HAVITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your order has shipped",
    "text": "Hi Sam, your order #1042 left our warehouse today."
  }'

{
  "sent": true,
  "message_id": "<1791630115483.e4xo969enah@acme.com>",
  "from": "support-agent@acme.com",
  "to": ["sam@example.com"], "cc": [], "bcc": [],
  "subject": "Your refund"
}

curl -X POST https://havitomail.com/api/v1/inboxes/$INBOX_ID/messages/42/reply \
  -H "Authorization: Bearer $HAVITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Thanks! Your refund was issued today."}'

curl -X PATCH https://havitomail.com/api/v1/inboxes/$INBOX_ID/messages/42 \
  -H "Authorization: Bearer $HAVITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seen": true, "move_to": "Archive"}'

{
  "id": "38e68acc-…",
  "url": "https://agent.acme.com/havito-webhook",
  "inbox_id": null,
  "events": ["message.received"],
  "active": true,
  "created_at": "2026-10-10T09:00:00.000Z",
  "last_delivery_at": null,
  "last_status": null,
  "last_error": null,
  "secret": "whsec_…"
}

// Node 18+ — poll an agent inbox and answer new mail
const API = "https://havitomail.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.HAVITO_API_KEY}`,
  "Content-Type": "application/json",
};
const inboxId = process.env.INBOX_ID;

const res = await fetch(`${API}/inboxes/${inboxId}/messages?unread=true`, { headers });
const { messages } = await res.json();

for (const msg of messages) {
  const answer = await myAgent.draftReply(msg.subject, msg.text); // your LLM call

  await fetch(`${API}/inboxes/${inboxId}/messages/${msg.uid}/reply`, {
    method: "POST",
    headers,
    body: JSON.stringify({ text: answer }), // threads under the original
  });
  await fetch(`${API}/inboxes/${inboxId}/messages/${msg.uid}`, {
    method: "PATCH",
    headers,
    body: JSON.stringify({ seen: true }),
  });
}

# Python 3 — requests
import os, requests

API = "https://havitomail.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['HAVITO_API_KEY']}"}
inbox = os.environ["INBOX_ID"]

msgs = requests.get(f"{API}/inboxes/{inbox}/messages",
                    params={"unread": "true", "limit": 20}, headers=H).json()["messages"]

for m in msgs:
    answer = my_agent.draft_reply(m["subject"], m["text"])  # your LLM call
    requests.post(f"{API}/inboxes/{inbox}/messages/{m['uid']}/reply",
                  json={"text": answer}, headers=H).raise_for_status()
    requests.patch(f"{API}/inboxes/{inbox}/messages/{m['uid']}",
                   json={"seen": True}, headers=H)