HermesAgentMail API

curl https://hermesagentmail.com/api/v1/inboxes \
  -H "Authorization: Bearer hm_live_..."

curl -X POST https://hermesagentmail.com/api/v1/inboxes \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "research",
    "agent_name": "Research Agent",
    "approval_mode": "required"
  }'

curl "https://hermesagentmail.com/api/v1/messages?limit=50" \
  -H "Authorization: Bearer $HERMES_API_KEY"

curl https://hermesagentmail.com/api/v1/messages/MESSAGE_ID \
  -H "Authorization: Bearer $HERMES_API_KEY"

curl -X POST https://hermesagentmail.com/api/v1/messages/MESSAGE_ID/reply \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Thanks for reaching out — here is the summary you asked for." }'

curl -X POST https://hermesagentmail.com/api/v1/outbound/OUTBOUND_MESSAGE_ID/request-send \
  -H "Authorization: Bearer $HERMES_API_KEY"

curl https://hermesagentmail.com/api/v1/inboxes \
  -H "Authorization: Bearer $HERMES_API_KEY"

# Requires scope: email:read.
{
  "data": [
    {
      "id": "8f4c1a2e-...",
      "address": "research@hermesagentmail.com",
      "agent": "Research Agent",
      "status": "active",
      "approval_mode": "required",
      "creates_tasks": true,
      "received": 128,
      "sent": 31,
      "created_at": "2026-06-30T09:12:00Z"
    }
  ]
}

curl -X POST https://hermesagentmail.com/api/v1/inboxes \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "research",
    "agent_name": "Research Agent",
    "approval_mode": "required"
  }'

# Requires scope: inbox:write. Returns 201.
{
  "data": {
    "id": "8f4c1a2e-...",
    "address": "research@hermesagentmail.com",
    "agent": "Research Agent",
    "status": "active",
    "approval_mode": "required",
    "created_at": "2026-07-05T02:41:00Z"
  }
}

curl "https://hermesagentmail.com/api/v1/messages?limit=50&thread_id=THREAD_ID" \
  -H "Authorization: Bearer $HERMES_API_KEY"

# Requires scope: email:read. Metadata + snippet only.
{
  "data": [
    {
      "id": "3b9d7c10-...",
      "thread_id": "5a2e8f44-...",
      "address": "research@hermesagentmail.com",
      "from": "customer@example.com",
      "subject": "Invoice question",
      "snippet": "Can you resend my latest invoice?",
      "created_at": "2026-07-04T12:00:00Z"
    }
  ]
}

curl https://hermesagentmail.com/api/v1/messages/MESSAGE_ID \
  -H "Authorization: Bearer $HERMES_API_KEY"

# Requires scope: email:read. Full message.
{
  "data": {
    "id": "3b9d7c10-...",
    "thread_id": "5a2e8f44-...",
    "from": "customer@example.com",
    "subject": "Invoice question",
    "text": "Can you resend my latest invoice?",
    "html": "<p>Can you resend my latest invoice?</p>",
    "headers": { "message-id": "<abc@example.com>" },
    "attachments": [
      { "filename": "invoice.pdf", "content_type": "application/pdf", "size": 48213 }
    ],
    "created_at": "2026-07-04T12:00:00Z"
  }
}

curl -X POST https://hermesagentmail.com/api/v1/messages/MESSAGE_ID/reply \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "plain text reply" }'

# Requires scope: email:draft. Returns 201.
{
  "data": {
    "outbound_message_id": "c71f0b3d-...",
    "approval_required": true,
    "status": "pending_approval"
  }
}

curl -X POST https://hermesagentmail.com/api/v1/outbound/OUTBOUND_MESSAGE_ID/request-send \
  -H "Authorization: Bearer $HERMES_API_KEY"

# Requires scope: email:send_request.
{
  "data": {
    "status": "sent" | "approval_required" | "blocked",
    "reason": "optional explanation when blocked"
  }
}

{
  "event": "email.received",
  "message_id": "3b9d7c10-...",
  "thread_id": "5a2e8f44-...",
  "workflow_id": "8f4c1a2e-...",
  "address": "research@hermesagentmail.com",
  "from": "customer@example.com",
  "subject": "Invoice question",
  "snippet": "Can you resend my latest invoice?",
  "requires_human_approval": true,
  "created_at": "2026-07-04T12:00:00Z"
}

import crypto from 'node:crypto'

export function verifyHermesWebhook({
  rawBody,
  timestamp,
  signature,
  secret, // Your whsec_ endpoint secret from the dashboard.
}: {
  rawBody: string
  timestamp: string
  signature: string
  secret: string
}): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  const a = Buffer.from(signature, 'hex')
  const b = Buffer.from(expected, 'hex')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

// Usage in a route handler: read the raw request body (before any
// JSON parsing) and the two X-HermesAgentMail-* headers, then reject
// the request with a 401 if verification fails.

{
  "mcpServers": {
    "hermesagentmail": {
      "url": "https://hermesagentmail.com/api/mcp",
      "headers": { "Authorization": "Bearer hm_live_..." }
    }
  }
}

{
  "error": {
    "code": "quota_exceeded",
    "message": "Your plan's inbox limit has been reached. Upgrade to add more inboxes."
  }
}