Skip to main content

​
Prerequisites

  • An openmail API key (configured during onboarding)
  • A webhook endpoint to receive inbound emails (use webhook.site for testing)

​
Base URL

https://api.openmail.sh
All requests require your API key as a Bearer token: 
Authorization: Bearer om_live_your_api_key_here

​
Step 1: Create an inbox

Every agent needs an inbox — a real email address it can send and receive from. 
curl -X POST https://api.openmail.sh/v1/inboxes \
  -H "Authorization: Bearer om_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "agent-123",
    "username": "jane"
  }'
Response: 
{
  "id": "inb_8f3a1b2c",
  "address": "jane@yourco.openmail.sh",
  "externalId": "agent-123",
  "createdAt": "2026-02-24T10:00:00.000Z"
}
Your agent now has an email address. If you omit username, we generate a random one.

​
Step 2: Send an email

curl -X POST https://api.openmail.sh/v1/inboxes/inb_8f3a1b2c/send \
  -H "Authorization: Bearer om_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "to": "support@airline.com",
    "subject": "Refund request #4421",
    "body": "Hi, I would like to request a refund for flight AA1234."
  }'
Response: 
{
  "messageId": "msg_2b1c3d4e",
  "threadId": "thr_9d4e5f6a",
  "providerMessageId": "mg_abc123",
  "status": "sent"
}
The Idempotency-Key header is required. If your request times out and you retry with the same key, we guarantee the email is only sent once.

​
Step 3: Receive replies via webhook

When someone replies to your agent’s email, we POST to your webhook URL. Your webhook should return 200 within 15 seconds.
Webhook payload
{
  "event": "message.received",
  "event_id": "evt_7f2a3b4c",
  "occurred_at": "2026-02-24T10:05:00.000Z",
  "delivered_at": "2026-02-24T10:05:01.000Z",
  "attempt": 1,
  "inbox_id": "inb_8f3a1b2c",
  "external_id": "agent-123",
  "thread_id": "thr_9d4e5f6a",
  "message": {
    "id": "msg_4c8d5e6f",
    "rfc_message_id": "<original@message.id>",
    "from": "support@airline.com",
    "to": "jane@yourco.openmail.sh",
    "cc": [],
    "subject": "Re: Refund request #4421",
    "body_text": "Hello, we've processed your refund of $342.00.",
    "attachments": [
      {
        "filename": "receipt.pdf",
        "contentType": "application/pdf",
        "sizeBytes": 42301,
        "url": "https://api.openmail.sh/v1/attachments/msg_4c8d5e6f/receipt.pdf"
      }
    ],
    "received_at": "2026-02-24T10:05:00.000Z"
  }
}
Use event_id to deduplicate — we deliver at-least-once and may retry.
Each webhook includes X-Signature and X-Timestamp headers for HMAC verification. See Webhooks for details.

​
Step 4: Reply in a thread

To continue the conversation, include threadId: 
curl -X POST https://api.openmail.sh/v1/inboxes/inb_8f3a1b2c/send \
  -H "Authorization: Bearer om_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "to": "support@airline.com",
    "subject": "Re: Refund request #4421",
    "body": "Thank you! Can you confirm when the refund will appear?",
    "threadId": "thr_9d4e5f6a"
  }'
We automatically set In-Reply-To and References headers so the reply threads correctly in the recipient’s email client.

​
Step 5: Read conversation history

Your agent can fetch the full thread at any time: 
curl https://api.openmail.sh/v1/threads/thr_9d4e5f6a/messages \
  -H "Authorization: Bearer om_live_..."
Response: 
{
  "threadId": "thr_9d4e5f6a",
  "subject": "Refund request #4421",
  "data": [
    {
      "id": "msg_2b1c3d4e",
      "direction": "outbound",
      "fromAddr": "jane@yourco.openmail.sh",
      "toAddr": "support@airline.com",
      "subject": "Refund request #4421",
      "bodyText": "Hi, I would like to request a refund...",
      "status": "sent",
      "createdAt": "2026-02-24T10:00:00.000Z"
    },
    {
      "id": "msg_4c8d5e6f",
      "direction": "inbound",
      "fromAddr": "support@airline.com",
      "toAddr": "jane@yourco.openmail.sh",
      "subject": "Re: Refund request #4421",
      "bodyText": "Hello, we've processed your refund...",
      "status": "received",
      "createdAt": "2026-02-24T10:05:00.000Z"
    },
    {
      "id": "msg_6e9f7a8b",
      "direction": "outbound",
      "fromAddr": "jane@yourco.openmail.sh",
      "toAddr": "support@airline.com",
      "subject": "Re: Refund request #4421",
      "bodyText": "Thank you! Can you confirm when...",
      "status": "sent",
      "createdAt": "2026-02-24T10:06:00.000Z"
    }
  ]
}

​
That’s it

Your agent can now send email, receive replies, maintain threaded conversations, and access attachments.

Core concepts

Learn about inboxes, threading, webhooks, and more.

API reference

Full endpoint documentation with request/response schemas.