OpenMail

https://docs.openmail.sh
Admin
OpenMail gives AI agents their own email addresses with sending, receiving, threading, and...
Tokens:44,435
Snippets:440
Trust Score:3.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install OpenClaw CLI

Source: https://docs.openmail.sh/integrations/openclaw

Install the OpenClaw command-line interface globally using npm. This is the first step to setting up your agent.

```bash
npm install -g @openmail/cli
```

--------------------------------

### Check OpenMail API Key Setup

Source: https://docs.openmail.sh/integrations/openclaw

Verify if the OpenMail API key has been set up by checking the `openmail.env` file. This command is useful for determining if `openmail setup` needs to be run.

```bash
grep -s OPENMAIL_API_KEY ~/.openclaw/openmail.env 2>/dev/null
```

--------------------------------

### Setup AI Agent Email with OpenMail CLI

Source: https://docs.openmail.sh/

Use the `openmail setup` command to create an inbox, write a skill file, and save credentials for your AI agent. This command automates the process of giving your agent an email address.

```bash
openmail setup
```

--------------------------------

### Check OpenMail Setup Status

Source: https://docs.openmail.sh/integrations/claude-code

Check if the OpenMail API key is already configured in your environment. This command helps determine if a full setup is required.

```bash
grep -s OPENMAIL_API_KEY ~/.claude/openmail.env 2>/dev/null
```

--------------------------------

### Install OpenMail Skill Plugin

Source: https://docs.openmail.sh/integrations/claude-code

Install the OpenMail skill plugin for Claude Code. This is the first step to enable email capabilities.

```bash
/plugin marketplace add openmailsh/skills
/plugin install openmail@openmailsh-skills
```

--------------------------------

### OpenClaw Skill File Content

Source: https://docs.openmail.sh/integrations/openclaw

The `SKILL.md` file contains the core instructions for the OpenClaw agent, defining its name, description, metadata, and setup procedures. It specifies requirements like the `openmail` binary and how to install the CLI.

```markdown
---
name: openmail
description: Gives the agent a real email address for sending and receiving email. Use this skill when the user needs to send a message to any person, service, or company; receive a reply; sign up for a website or service and confirm the account; receive a verification code, magic link, or password reset; handle an inbound support request; or interact with anything that communicates by email — even if the user doesn't say "email" explicitly and instead says things like "reach out to them", "contact support", "sign up", "wait for their reply", "check if they responded", or "subscribe".
metadata: {"openclaw":{"emoji":"📬","requires":{"bins":["openmail"]},"primaryEnv":"OPENMAIL_API_KEY","install":[{"id":"npm","kind":"node","package":"@openmail/cli","bins":["openmail"],"label":"Install OpenMail CLI (npm)"}]}}
---

# OpenMail

OpenMail gives this agent a real email address for sending and receiving.
The `openmail` CLI handles all API calls — auth, idempotency, and inbox
resolution are automatic.

## Setup

Check whether setup has already been done:

```bash
grep -s OPENMAIL_API_KEY ~/.openclaw/openmail.env 2>/dev/null
```

If the key is missing or blank, run:

```bash
openmail setup
```

This opens your browser to sign in, prompts for a mailbox name, and writes credentials automatically.

Your email address is `$OPENMAIL_ADDRESS`.

```

--------------------------------

### Reset Claude Code Agent Setup

Source: https://docs.openmail.sh/integrations/skill-files/setup

To reset the setup for the Claude Code agent, use this command with the --reset flag.

```bash
npx @openmail/cli setup --agent claude-code --reset
```

--------------------------------

### Create a New Inbox

Source: https://docs.openmail.sh/integrations/skill-files/setup

After initial setup, use this command to create additional mailboxes with specified names.

```bash
npx @openmail/cli inbox create --mailbox-name "support" --display-name "Support"
```

--------------------------------

### CLI Setup Command

Source: https://docs.openmail.sh/integrations/skill-files/errors

Run this command to set up your OpenMail CLI if the inbox ID is missing or configuration is not found.

```bash
openmail setup --api-key "om_live_..."
```

--------------------------------

### Wire the agent with OpenMail tools

Source: https://docs.openmail.sh/integrations/agent-frameworks

Example of how to stream text from an AI model, providing the OpenMail tools to the agent and processing the response.

```APIDOC
## Stream Text with Tools

### Description
Initiates a streaming text generation process using a specified AI model and a set of tools. The agent can then use these tools to interact with external services like OpenMail.

### Method
streamText

### Parameters
- **model** (object) - Required - The AI model to use (e.g., openai("gpt-4o"))
- **tools** (object) - Required - An object containing the available tools (e.g., { sendEmail, checkInbox, readThread })
- **maxSteps** (integer) - Optional - The maximum number of tool-use steps the agent can take.
- **prompt** (string) - Required - The initial prompt for the AI model.

### Response
- **textStream** (ReadableStream) - A stream of text parts generated by the AI model.
```

--------------------------------

### Manage Inboxes via CLI

Source: https://docs.openmail.sh/integrations/skill-files/api

Commands for listing, creating, getting details of, and deleting inboxes.

```bash
# List all inboxes
openmail inbox list

# Create an inbox
openmail inbox create --mailbox-name "support" --display-name "Support"

# Get inbox details
openmail inbox get --id "inb_..."

# Delete an inbox
openmail inbox delete --id "inb_..."
```

--------------------------------

### Claude Code Agent Setup

Source: https://docs.openmail.sh/integrations/skill-files/setup

Use this command to set up the Claude Code agent. It handles browser sign-in or API key input, mailbox creation, and writes necessary configuration files.

```bash
npx @openmail/cli setup --agent claude-code
```

--------------------------------

### Manage Threads via CLI

Source: https://docs.openmail.sh/integrations/skill-files/api

Commands for listing, getting, and marking threads as read or unread.

```bash
# List unread threads (preferred for checking new mail)
openmail threads list --is-read false

# List all threads
openmail threads list

# List with pagination
openmail threads list --limit 20 --offset 0

# Get messages in a thread (oldest-first)
openmail threads get --thread-id "thr_..."

# Mark thread as read
openmail threads read --thread-id "thr_..."

# Mark thread as unread
openmail threads unread --thread-id "thr_..."
```

--------------------------------

### Connect to WebSocket for Inbound Emails (Python)

Source: https://docs.openmail.sh/guides/api-integration

This Python example demonstrates connecting to the WebSocket endpoint for real-time email delivery. Ensure your API key is set in the environment variables.

```python
import asyncio, json, os, websockets

OPENMAIL_API_KEY = os.environ["OPENMAIL_API_KEY"]

async def listen():
    uri = "wss://api.openmail.sh/v1/ws"
    headers = {"Authorization": f"Bearer {OPENMAIL_API_KEY}"}

    async for ws in websockets.connect(uri, extra_headers=headers):
        try:
            await ws.send(json.dumps({"type": "subscribe"}))
            async for raw in ws:
                event = json.loads(raw)
                if event.get("event") == "message.received":
                    container = get_container_by_inbox_id(event["inbox_id"])
                    container.deliver_email(thread_id=event["thread_id"], message=event["message"])
        except websockets.ConnectionClosed:
            continue
asyncio.run(listen())
```

--------------------------------

### Verify API Key in Environment

Source: https://docs.openmail.sh/integrations/skill-files/errors

Check your OpenMail API key by grepping the environment file. The key should start with 'om_'.

```bash
grep OPENMAIL_API_KEY ~/.openclaw/openmail.env
```

--------------------------------

### Set Environment Variables for OpenMail

Source: https://docs.openmail.sh/integrations/agent-frameworks

Set these environment variables before running any of the examples. Ensure you have an OpenMail account and API key.

```bash
OPENMAIL_API_KEY=om_live_...
OPENMAIL_INBOX_ID=inb_...
OPENMAIL_ADDRESS=agent@example.openmail.sh
```

--------------------------------

### Production WebSocket Connection with Reconnection

Source: https://docs.openmail.sh/guides/websockets/quickstart

This example demonstrates a robust WebSocket connection for production environments. It includes automatic reconnection with exponential backoff and uses `last_event_id` to ensure no events are lost during disconnections. Ensure your `OPENMAIL_API_KEY` is set in your environment variables.

```javascript
const WebSocket = require("ws");

const OPENMAIL_API_KEY = process.env.OPENMAIL_API_KEY;
let lastEventId = null;
let retries = 0;

function connect() {
  const ws = new WebSocket("wss://api.openmail.sh/v1/ws", {
    headers: { Authorization: `Bearer ${OPENMAIL_API_KEY}` },
  });

  ws.on("open", () => {
    console.log("Connected to OpenMail");
    const sub = { type: "subscribe" };
    if (lastEventId) sub.last_event_id = lastEventId;
    ws.send(JSON.stringify(sub));
    retries = 0;
  });

  ws.on("message", (data) => {
    const event = JSON.parse(data);

    if (event.type === "subscribed") {
      console.log("Subscribed — inboxes:", event.inbox_ids, "events:", event.event_types);
      return;
    }

    if (event.event === "message.received") {
      lastEventId = event.event_id;
      console.log(`New email from: ${event.message.from}`);
      console.log(`Subject: ${event.message.subject}`);

      const container = getContainerByInboxId(event.inbox_id);
      container.deliverEmail({
        threadId: event.thread_id,
        message: event.message,
      });
    }
  });

  ws.on("close", (code) => {
    console.log(`Disconnected (${code}), reconnecting...`);
    setTimeout(connect, Math.min(1000 * Math.pow(2, retries++), 30000));
  });

  ws.on("error", (err) => {
    console.error("WebSocket error:", err.message);
  });
}

connect();

```

```python
import asyncio, json, os
from websockets import connect

OPENMAIL_API_KEY = os.environ["OPENMAIL_API_KEY"]
last_event_id = None

async def listen():
    global last_event_id
    uri = "wss://api.openmail.sh/v1/ws"
    headers = {"Authorization": f"Bearer {OPENMAIL_API_KEY}"}

    async for ws in connect(uri, extra_headers=headers):
        try:
            sub = {"type": "subscribe"}
            if last_event_id:
                sub["last_event_id"] = last_event_id
            await ws.send(json.dumps(sub))

            async for raw in ws:
                event = json.loads(raw)

                if event.get("type") == "subscribed":
                    print("Subscribed — inboxes:", event["inbox_ids"], "events:", event["event_types"])
                    continue

                if event.get("event") == "message.received":
                    last_event_id = event["event_id"]
                    print(f"New email from: {event['message']['from']}")
                    print(f"Subject: {event['message']['subject']}")

                    container = get_container_by_inbox_id(event["inbox_id"])
                    container.deliver_email(
                        thread_id=event["thread_id"],
                        message=event["message"],
                    )

        except Exception:
            continue  # auto-reconnects

asyncio.run(listen())

```

--------------------------------

### Connect to WebSocket with Python

Source: https://docs.openmail.sh/concepts/websockets

This Python snippet demonstrates connecting to the WebSocket endpoint. It uses the 'websockets' library and authenticates using an API key passed in the Authorization header. Ensure the 'websockets' and 'asyncio' libraries are installed.

```python
import asyncio, os
from websockets import connect

async def main():
    uri = "wss://api.openmail.sh/v1/ws"
    headers = {"Authorization": f"Bearer {os.environ['OPENMAIL_API_KEY']}"}

    async with connect(uri, extra_headers=headers) as ws:
        # connected — send subscribe, receive events
        ...

asyncio.run(main())
```

--------------------------------

### Connect to WebSocket with Node.js

Source: https://docs.openmail.sh/concepts/websockets

Use this snippet to establish a WebSocket connection using Node.js. Authenticate with your API key via the Authorization header. Ensure the 'ws' package is installed.

```javascript
const WebSocket = require("ws");

const ws = new WebSocket("wss://api.openmail.sh/v1/ws", {
  headers: { Authorization: `Bearer ${process.env.OPENMAIL_API_KEY}` },
});
```

--------------------------------

### Subscribe to Events

Source: https://docs.openmail.sh/pages/websockets/protocol

Send a `subscribe` message to start receiving events. You can filter by inbox, event type, or both. Subscriptions accumulate.

```APIDOC
## Subscribe

Send a `subscribe` message to start receiving events. You can filter by inbox, event type, or both.

### Request Body Examples

Subscribe to all inboxes and all events:
```json
{ "type": "subscribe" }
```

Subscribe to specific inboxes:
```json
{ "type": "subscribe", "inbox_ids": ["inb_8f3a1b2c", "inb_2d4e6f8a"] }
```

Subscribe to specific event types:
```json
{
  "type": "subscribe",
  "inbox_ids": ["inb_8f3a1b2c"],
  "event_types": ["message.received"]
}
```

### Response Example (Subscribed Confirmation)

The server responds with a `subscribed` confirmation that echoes back your active subscriptions:
```json
{ "type": "subscribed", "inbox_ids": [], "event_types": [] }
```

When `inbox_ids` is empty in the response, you are subscribed to all inboxes on your account. When `event_types` is empty, you receive all event types. Otherwise, the arrays list your specific filters.

Subscriptions accumulate — sending multiple `subscribe` messages adds to your existing subscriptions.

**Note:** When subscribing to specific `inbox_ids`, OpenMail verifies you own each inbox. Unowned inbox IDs return an error.
```

--------------------------------

### Inbox Address Format Example

Source: https://docs.openmail.sh/concepts/inboxes

Illustrates the standard address format for an inbox using the `openmail.sh` domain. The `mailboxName` is optional; if omitted, a random string is generated.

```plaintext
{mailboxName}@openmail.sh
```

```plaintext
support@openmail.sh
```

--------------------------------

### Verify OpenMail CLI Status

Source: https://docs.openmail.sh/integrations/skill-files/setup

Check the current status of your OpenMail CLI setup and configurations with this command.

```bash
npx @openmail/cli status
```

--------------------------------

### Handle Inbound Emails via Webhook (Python)

Source: https://docs.openmail.sh/guides/api-integration

This Python Flask example demonstrates how to verify the webhook signature using HMAC-SHA256 and process incoming email events.

```python
import hmac, hashlib, os

@app.post("/webhooks/openmail")
def handle_webhook():
    payload = request.get_data(as_text=True)
    timestamp = request.headers.get("X-Timestamp")
    signature = request.headers.get("X-Signature")
    expected = hmac.new(
        os.environ["OPENMAIL_WEBHOOK_SECRET"].encode(),
        f"{timestamp}.{payload}".encode(),
        hashlib.sha256,
    ).hexdigest()

```

--------------------------------

### Invalid Authentication Response

Source: https://docs.openmail.sh/api-reference/authentication

This is an example of the JSON response received when authentication fails due to a missing or invalid `Authorization` header.

```APIDOC
## Invalid authentication

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
// 401 Unauthorized
{
  "error": "unauthorized",
  "message": "Missing or invalid Authorization header"
}
```
```

--------------------------------

### Handle Inbound Emails via Webhook (Node.js)

Source: https://docs.openmail.sh/guides/api-integration

This Node.js example shows how to verify the HMAC-SHA256 signature of incoming webhook requests and process the 'message.received' event.

```javascript
const crypto = require("crypto");

app.post("/webhooks/openmail", (req, res) => {
  const signature = req.headers["x-signature"];
  const timestamp = req.headers["x-timestamp"];
  const expected = crypto
    .createHmac("sha256", process.env.OPENMAIL_WEBHOOK_SECRET)
    .update(`${timestamp}.${JSON.stringify(req.body)}`)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"))) {
    return res.status(401).send("Invalid signature");
  }

  const { event, inbox_id, thread_id, message } = req.body;
  if (event === "message.received") {
    const container = getContainerByInboxId(inbox_id);
    container.deliverEmail({ threadId: thread_id, message });
  }

  res.status(200).send("OK");
});
```

--------------------------------

### Manage Email Threads with OpenMail CLI

Source: https://docs.openmail.sh/integrations/claude-code

A collection of commands for managing email threads, including listing unread threads, getting thread details, marking threads as read, and unread.

```bash
openmail threads list --is-read false
openmail threads get --thread-id "thr_..."
openmail threads read --thread-id "thr_..."
openmail threads unread --thread-id "thr_..."
```

--------------------------------

### Sign Up and Confirm Workflow

Source: https://docs.openmail.sh/integrations/claude-code

Steps for signing up for a service using the agent's email address and confirming via a link extracted from an email.

```bash
openmail threads list --is-read false
```

```bash
openmail threads read --thread-id "thr_..."
```

--------------------------------

### OpenAPI Specification for Get Thread Messages

Source: https://docs.openmail.sh/api-reference/get-thread-messages

This OpenAPI specification defines the GET /v1/threads/{id}/messages endpoint. It includes request parameters, response schemas for a successful retrieval of a thread with its messages, and component schemas for messages and attachments.

```yaml
openapi: 3.0.3
info:
  title: OpenMail API
  description: >-
    Email infrastructure API for AI agents. Create inboxes, send and receive
    email, and get real-time notifications via webhooks.
  version: 1.0.0
  license:
    name: Proprietary
servers:
  - url: https://api.openmail.sh
security:
  - bearerAuth: []
paths:
  /v1/threads/{id}/messages:
    get:
      summary: Get thread messages
      operationId: getThreadMessages
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Thread with messages
          content:
            application/json:
              schema:
                type: object
                properties:
                  threadId:
                    type: string
                  subject:
                    type: string
                  isRead:
                    type: boolean
                    description: Whether the thread has been marked as read
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
components:
  schemas:
    Message:
      type: object
      properties:
        id:
          type: string
        threadId:
          type: string
        direction:
          type: string
          enum:
            - inbound
            - outbound
        fromAddr:
          type: string
        toAddr:
          type: string
        subject:
          type: string
        bodyText:
          type: string
        bodyHtml:
          type: string
        attachments:
          type: array
          items:
            type: object
            properties:
              filename:
                type: string
              contentType:
                type: string
              sizeBytes:
                type: integer
              url:
                type: string
                description: Signed URL for download
        status:
          type: string
          enum:
            - pending
            - sent
            - received
            - failed
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

```

--------------------------------

### Connect to WebSocket with CLI (websocat)

Source: https://docs.openmail.sh/concepts/websockets

Connect to the WebSocket endpoint using the 'websocat' command-line tool. This method is useful for quick testing or environments where custom headers cannot be easily set. Replace 'YOUR_API_KEY' with your actual API key.

```bash
websocat "wss://api.openmail.sh/v1/ws?token=YOUR_API_KEY"
```

--------------------------------

### OpenAPI Specification for Get Attachment

Source: https://docs.openmail.sh/api-reference/get-attachment

This OpenAPI specification defines the `GET /v1/attachments/{messageId}/{filename}` endpoint. It outlines the request parameters, including `messageId` and `filename`, and the possible responses, such as a 302 redirect to the attachment URL or a 404 error if the attachment is not found.

```yaml
openapi: 3.0.3
info:
  title: OpenMail API
  description: >-
    Email infrastructure API for AI agents. Create inboxes, send and receive
    email, and get real-time notifications via webhooks.
  version: 1.0.0
  license:
    name: Proprietary
servers:
  - url: https://api.openmail.sh
security:
  - bearerAuth: []
paths:
  /v1/attachments/{messageId}/{filename}:
    get:
      summary: Get attachment
      description: Returns a 302 redirect to a signed URL for the attachment.
      operationId: getAttachment
      parameters:
        - name: messageId
          in: path
          required: true
          schema:
            type: string
        - name: filename
          in: path
          required: true
          schema:
            type: string
      responses:
        '302':
          description: Redirect to attachment URL
        '404':
          description: Attachment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

```

--------------------------------

### Get Inbox OpenAPI Specification

Source: https://docs.openmail.sh/api-reference/get-inbox

This OpenAPI 3.0.3 specification defines the GET /v1/inboxes/{id} endpoint for retrieving inbox details. It includes request parameters, response schemas for success (200) and not found (404) cases, and security scheme definitions.

```yaml
openapi: 3.0.3
info:
  title: OpenMail API
  description: >-
    Email infrastructure API for AI agents. Create inboxes, send and receive
    email, and get real-time notifications via webhooks.
  version: 1.0.0
  license:
    name: Proprietary
servers:
  - url: https://api.openmail.sh
security:
  - bearerAuth: []
paths:
  /v1/inboxes/{id}:
    get:
      summary: Get inbox
      operationId: getInbox
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Inbox details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Inbox'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Inbox:
      type: object
      properties:
        id:
          type: string
          description: OpenMail inbox ID
        address:
          type: string
          format: email
          description: Full email address
        displayName:
          type: string
          description: Sender display name
          nullable: true
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

```

--------------------------------

### Connect, Subscribe, and Log Events (Python)

Source: https://docs.openmail.sh/guides/websockets/quickstart

This Python snippet demonstrates how to connect to the OpenMail WebSocket, authenticate using an API key from environment variables, subscribe to events, and print received message details. It utilizes the `websockets` library.

```python
import asyncio, json, os
from websockets import connect

async def main():
    uri = "wss://api.openmail.sh/v1/ws"
    headers = {"Authorization": f"Bearer {os.environ['OPENMAIL_API_KEY']}"}

    async with connect(uri, extra_headers=headers) as ws:
        await ws.send(json.dumps({"type": "subscribe"}))

        async for raw in ws:
            event = json.loads(raw)

            if event.get("type") == "subscribed":
                print("Subscribed — inboxes:", event["inbox_ids"], "events:", event["event_types"])
            elif event.get("event") == "message.received":
                print(f"From: {event['message']['from']}")
                print(f"Subject: {event['message']['subject']}")
                print(f"Body: {event['message']['body_text']}")

asyncio.run(main())
```

--------------------------------

### Get Inbox

Source: https://docs.openmail.sh/llms.txt

Retrieves details for a specific email inbox.

```APIDOC
## GET /inboxes/{inboxId}

### Description
Retrieves details for a specific email inbox.

### Method
GET

### Endpoint
/inboxes/{inboxId}

### Parameters
#### Path Parameters
- **inboxId** (string) - Required - The ID of the inbox to retrieve.
```

--------------------------------

### read_thread

Source: https://docs.openmail.sh/integrations/agent-frameworks

Get all messages in a thread (oldest first) and mark it as read.

```APIDOC
## read_thread

### Description
Get all messages in a thread (oldest first) and mark it as read.

### Method
GET

### Endpoint
/threads/{threadId}/messages

### Parameters
#### Path Parameters
- **threadId** (string) - Required - Thread ID to read

### Response
#### Success Response (200)
- **messages** (array) - An array of message objects within the thread

### Note
This operation also marks the thread as read via a PATCH request to `/threads/{threadId}`.
```

--------------------------------

### Connect, Subscribe, and Log Events (Node.js)

Source: https://docs.openmail.sh/guides/websockets/quickstart

Use this Node.js snippet to establish a WebSocket connection, authenticate with your API key, subscribe to events, and log received messages. Ensure your OPENMAIL_API_KEY environment variable is set.

```javascript
const WebSocket = require("ws");

const ws = new WebSocket("wss://api.openmail.sh/v1/ws", {
  headers: { Authorization: `Bearer ${process.env.OPENMAIL_API_KEY}` },
});

ws.on("open", () => {
  ws.send(JSON.stringify({ type: "subscribe" }));
});

ws.on("message", (data) => {
  const event = JSON.parse(data);

  if (event.type === "subscribed") {
    console.log("Subscribed — inboxes:", event.inbox_ids, "events:", event.event_types);
  } else if (event.event === "message.received") {
    console.log(`From: ${event.message.from}`);
    console.log(`Subject: ${event.message.subject}`);
    console.log(`Body: ${event.message.body_text}`);
  }
});
```

--------------------------------

### Get Attachment

Source: https://docs.openmail.sh/api-reference/get-attachment

Returns a 302 redirect to a signed URL for the attachment.

```APIDOC
## GET /v1/attachments/{messageId}/{filename}

### Description
Returns a 302 redirect to a signed URL for the attachment.

### Method
GET

### Endpoint
/v1/attachments/{messageId}/{filename}

### Parameters
#### Path Parameters
- **messageId** (string) - Required - The ID of the message the attachment belongs to.
- **filename** (string) - Required - The name of the attachment file.

### Response
#### Success Response (302)
Description: Redirect to attachment URL

#### Error Response (404)
Description: Attachment not found
- **error** (string) - Description of the error.
- **message** (string) - More detailed error message.
```

--------------------------------

### Get Thread Messages

Source: https://docs.openmail.sh/api-reference/get-thread-messages

Fetches all messages belonging to a specific thread.

```APIDOC
## GET /v1/threads/{id}/messages

### Description
Retrieves messages for a given thread ID.

### Method
GET

### Endpoint
/v1/threads/{id}/messages

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the thread.

### Response
#### Success Response (200)
- **threadId** (string) - The ID of the thread.
- **subject** (string) - The subject of the thread.
- **isRead** (boolean) - Indicates if the thread has been read.
- **data** (array) - An array of message objects.
  - **id** (string) - The unique identifier of the message.
  - **threadId** (string) - The ID of the thread the message belongs to.
  - **direction** (string) - The direction of the message (inbound or outbound).
  - **fromAddr** (string) - The sender's email address.
  - **toAddr** (string) - The recipient's email address.
  - **subject** (string) - The subject of the message.
  - **bodyText** (string) - The plain text content of the message.
  - **bodyHtml** (string) - The HTML content of the message.
  - **attachments** (array) - An array of attachment objects.
    - **filename** (string) - The name of the attachment.
    - **contentType** (string) - The MIME type of the attachment.
    - **sizeBytes** (integer) - The size of the attachment in bytes.
    - **url** (string) - A signed URL for downloading the attachment.
  - **status** (string) - The status of the message (pending, sent, received, failed).
  - **createdAt** (string) - The timestamp when the message was created.
```

--------------------------------

### GET /v1/inboxes/{id}/threads

Source: https://docs.openmail.sh/integrations/skill-files/api

Retrieve a list of threads for a given inbox.

```APIDOC
## GET /v1/inboxes/{id}/threads

### Description
Retrieve a list of threads for a given inbox.

### Method
GET

### Endpoint
`/v1/inboxes/{id}/threads`

### Query Parameters
* `is_read` (boolean, optional) - Filter by read status.
* `limit` (integer, optional) - Number of threads to return.
* `offset` (integer, optional) - Offset for pagination.
```

--------------------------------

### Get Inbox by ID

Source: https://docs.openmail.sh/api-reference/get-inbox

Fetches the details of a specific inbox by providing its unique identifier.

```APIDOC
## GET /v1/inboxes/{id}

### Description
Retrieves the details of a specific inbox.

### Method
GET

### Endpoint
/v1/inboxes/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the inbox.

### Response
#### Success Response (200)
- **id** (string) - OpenMail inbox ID
- **address** (string) - Full email address
- **displayName** (string) - Sender display name (nullable)
- **createdAt** (string) - Timestamp when the inbox was created

#### Response Example
```json
{
  "id": "inbox_abc123",
  "address": "user@example.com",
  "displayName": "User Name",
  "createdAt": "2023-10-27T10:00:00Z"
}
```

#### Error Response (404)
- **error** (string) - Error type
- **message** (string) - Error message

#### Response Example
```json
{
  "error": "not_found",
  "message": "Inbox not found"
}
```
```

--------------------------------

### Create Inbox and Write Environment Variables (Python)

Source: https://docs.openmail.sh/guides/api-integration

Creates a new inbox using the OpenMail API and appends essential environment variables (API key, inbox ID, address) to a specified container environment file. Requires OPENMAIL_API_KEY to be set in the environment.

```python
import os, requests

OPENMAIL_API_KEY = os.environ["OPENMAIL_API_KEY"]

def create_agent_inbox(user_id: str, container_env_path: str) -> dict:
    response = requests.post(
        "https://api.openmail.sh/v1/inboxes",
        headers={"Authorization": f"Bearer {OPENMAIL_API_KEY}"},
        json={"mailboxName": user_id},
    )
    response.raise_for_status()
    inbox = response.json()
    # inbox["id"]      → "inb_8f3a1b2c"
    # inbox["address"] → "jane@openmail.sh"

    with open(container_env_path, "a") as f:
        f.write(f"OPENMAIL_API_KEY={OPENMAIL_API_KEY}\n")
        f.write(f"OPENMAIL_INBOX_ID={inbox['id']}\n")
        f.write(f"OPENMAIL_ADDRESS={inbox['address']}\n")

    return inbox
```

--------------------------------

### Create LangChain Agent with OpenMail Tools

Source: https://docs.openmail.sh/integrations/agent-frameworks

Instantiate a LangChain agent using ChatOpenAI and the previously defined OpenMail tools. This agent can then process user requests involving email operations.

```python
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

agent = create_react_agent(
    ChatOpenAI(model="gpt-4o"),
    tools=[send_email, check_inbox, read_thread],
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Check my inbox and summarise any new emails."}]}
)
```

--------------------------------

### GET /v1/inboxes/{id}/messages

Source: https://docs.openmail.sh/integrations/skill-files/api

Retrieves messages from a specified inbox. Supports filtering by direction and pagination.

```APIDOC
## GET /v1/inboxes/{id}/messages

### Description
Retrieves messages from a specified inbox. Supports filtering by direction and pagination.

### Method
GET

### Endpoint
/v1/inboxes/{id}/messages

### Parameters
#### Query Parameters
- **direction** (string) - Optional - Filters messages by direction (e.g., 'inbound').
- **limit** (integer) - Optional - The maximum number of messages to return.
- **offset** (integer) - Optional - The number of messages to skip before returning results.

### Request Example
```
GET /v1/inboxes/{id}/messages?direction=inbound&limit=20&offset=0
```
```

--------------------------------

### GET /v1/threads/{id}/messages

Source: https://docs.openmail.sh/integrations/skill-files/api

Retrieve messages within a specific thread, sorted from oldest to newest.

```APIDOC
## GET /v1/threads/{id}/messages

### Description
Retrieve messages within a specific thread, sorted from oldest to newest.

### Method
GET

### Endpoint
`/v1/threads/{id}/messages`
```

--------------------------------

### List Messages via CLI

Source: https://docs.openmail.sh/integrations/skill-files/api

Commands to list inbound or outbound messages with pagination options.

```bash
# List inbound messages
openmail messages list --direction inbound --limit 20

# List outbound messages
openmail messages list --direction outbound

# With pagination
openmail messages list --direction inbound --limit 50 --offset 100
```

--------------------------------

### Threads (CLI)

Source: https://docs.openmail.sh/integrations/skill-files/api

Manage email threads using the OpenMail CLI. List, get, mark as read/unread.

```APIDOC
## Threads

### Description
Manage email threads using the OpenMail CLI. List, get, mark as read/unread.

### CLI Commands
```bash
# List unread threads (preferred for checking new mail)
openmail threads list --is-read false

# List all threads
openmail threads list

# List with pagination
openmail threads list --limit 20 --offset 0

# Get messages in a thread (oldest-first)
openmail threads get --thread-id "thr_..."

# Mark thread as read
openmail threads read --thread-id "thr_..."

# Mark thread as unread
openmail threads unread --thread-id "thr_..."
```

### Thread Object
```json
{
  "id": "thr_...",
  "inboxId": "inb_...",
  "subject": "Re: Hello",
  "lastMessageAt": "2024-01-01T00:00:00.000Z",
  "isRead": false,
  "messageCount": 3
}
```
```

--------------------------------

### Send Email with Attachments using CLI

Source: https://docs.openmail.sh/concepts/attachments

Utilize the OpenMail CLI to send emails with attachments. Use the --attach flag for each file you want to include.

```bash
openmail send --to recipient@example.com --subject "Monthly report" \
    --body "See the attached report." \
    --attach report.pdf --attach chart.png
```

--------------------------------

### List threads

Source: https://docs.openmail.sh/guides/api-integration

Get a list of all email threads associated with your inbox. You can specify a limit for the number of threads returned.

```APIDOC
## GET /v1/inboxes/{OPENMAIL_INBOX_ID}/threads

### Description
Retrieves a list of email threads for a given inbox.

### Method
GET

### Endpoint
/v1/inboxes/{OPENMAIL_INBOX_ID}/threads

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of threads to return.

### Response
#### Success Response (200)
- **threads** (array) - A list of thread objects.
```

--------------------------------

### Inboxes (CLI)

Source: https://docs.openmail.sh/integrations/skill-files/api

Manage email inboxes using the OpenMail CLI. List, create, get details, and delete.

```APIDOC
## Inboxes

### Description
Manage email inboxes using the OpenMail CLI. List, create, get details, and delete.

### CLI Commands
```bash
# List all inboxes
openmail inbox list

# Create an inbox
openmail inbox create --mailbox-name "support" --display-name "Support"

# Get inbox details
openmail inbox get --id "inb_..."

# Delete an inbox
openmail inbox delete --id "inb_..."
```

### Inbox Object
```json
{
  "id": "inb_...",
  "address": "support@example.openmail.sh",
  "displayName": "Support",
  "createdAt": "2024-01-01T00:00:00.000Z"
}
```
```

--------------------------------

### Implement Email Sending, Checking, and Reading Functions

Source: https://docs.openmail.sh/integrations/agent-frameworks

Use these JavaScript functions with any framework supporting function calling. Ensure OPENMAIL_API_KEY and OPENMAIL_INBOX_ID environment variables are set.

```javascript
const API_KEY = process.env.OPENMAIL_API_KEY;
const INBOX_ID = process.env.OPENMAIL_INBOX_ID;
const BASE = "https://api.openmail.sh/v1";
const headers = { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" };

async function sendEmail({ to, subject, body, threadId }) {
  const resp = await fetch(`${BASE}/inboxes/${INBOX_ID}/send`, {
    method: "POST",
    headers: { ...headers, "Idempotency-Key": crypto.randomUUID() },
    body: JSON.stringify({ to, subject, body, ...(threadId && { threadId }) }),
  });
  if (!resp.ok) throw new Error(`OpenMail ${resp.status}`);
  return resp.json();
}

async function checkInbox() {
  const resp = await fetch(
    `${BASE}/inboxes/${INBOX_ID}/threads?is_read=false&limit=20`,
    { headers },
  );
  if (!resp.ok) throw new Error(`OpenMail ${resp.status}`);
  return resp.json();
}

async function readThread(threadId) {
  const resp = await fetch(`${BASE}/threads/${threadId}/messages`, { headers });
  if (!resp.ok) throw new Error(`OpenMail ${resp.status}`);
  const messages = await resp.json();

  await fetch(`${BASE}/threads/${threadId}`, {
    method: "PATCH",
    headers,
    body: JSON.stringify({ is_read: true }),
  });
  return messages;
}
```

--------------------------------

### CLI Status and Diagnostics

Source: https://docs.openmail.sh/integrations/skill-files/api

Run `openmail status` to check API connection, default inbox, and bridge status.

```bash
openmail status
```

--------------------------------

### Wire AI Agent with OpenMail.sh Tools (TypeScript)

Source: https://docs.openmail.sh/integrations/agent-frameworks

Streams text from an AI model, utilizing defined OpenMail.sh tools to process a prompt. Sets a maximum of 5 tool execution steps.

```typescript
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

const result = streamText({
  model: openai("gpt-4o"),
  tools: { sendEmail, checkInbox, readThread },
  maxSteps: 5,
  prompt: "Check my inbox and summarise any new emails.",
});

for await (const part of result.textStream) {
  process.stdout.write(part);
}
```

--------------------------------

### OpenClaw JSON Configuration for OpenMail

Source: https://docs.openmail.sh/integrations/openclaw

This JSON configuration merges OpenMail into your OpenClaw setup, enabling the skill and defining how inbound email notifications are routed to your agent.

```json
{
  "skills": {
    "entries": {
      "openmail": {
        "enabled": true,
        "env": {
          "OPENMAIL_API_KEY": "om_live_...",
          "OPENMAIL_INBOX_ID": "inb_...",
          "OPENMAIL_ADDRESS": "agent-name@example.openmail.sh",
          "OPENMAIL_MODE": "notify"
        }
      }
    }
  },
  "hooks": {
    "mappings": [
      {
        "match": { "path": "openmail" },
        "action": "agent",
        "wakeMode": "now",
        "name": "OpenMail",
        "messageTemplate": "New email from {{email.sender}} — \"{{email.subject}}\"\n\n{{email.body_text}}"
      }
    ]
  }
}
```

--------------------------------

### Send Email via CLI

Source: https://docs.openmail.sh/integrations/skill-files/api

Use the `openmail send` command to send emails. Supports plain text, HTML, attachments, and replies to existing threads.

```bash
openmail send \
  --to "recipient@example.com" \
  --subject "Subject" \
  --body "Plain text body."

# Reply in thread (subject ignored)
openmail send \
  --to "recipient@example.com" \
  --thread-id "thr_..." \
  --body "Reply body."

# With HTML and attachments
openmail send \
  --to "recipient@example.com" \
  --subject "Report" \
  --body "See attached." \
  --body-html "<p>See attached.</p>" \
  --attach ./report.pdf \
  --attach ./data.csv
```

--------------------------------

### CLI Error: Missing Inbox ID

Source: https://docs.openmail.sh/integrations/skill-files/errors

This error occurs when the OpenMail CLI is used without an initialized inbox. It prompts the user to run the setup command.

```APIDOC
## CLI Errors

### `missing inbox id; run 'openmail init' or pass --inbox-id`

Setup hasn't been run, or `~/.openclaw/openmail.env` is missing. Run:

```bash
openmail setup --api-key "om_live_..."
```
```

--------------------------------

### Get Specific Thread Details

Source: https://docs.openmail.sh/quickstart

Retrieve detailed information about a specific email thread using its unique thread ID. This allows for in-depth analysis of conversations.

```bash
openmail threads get --thread-id <thread-id>
```

--------------------------------

### Create Inbox and Write Environment Variables (Node.js)

Source: https://docs.openmail.sh/guides/api-integration

Creates a new inbox via the OpenMail API and appends necessary environment variables (API key, inbox ID, address) to a specified container environment file. Ensure OPENMAIL_API_KEY is set in your environment.

```javascript
const fs = require("fs/promises");

const OPENMAIL_API_KEY = process.env.OPENMAIL_API_KEY;

async function createAgentInbox(userId, containerEnvPath) {
    const response = await fetch("https://api.openmail.sh/v1/inboxes", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${OPENMAIL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ mailboxName: userId }),
    });

    if (!response.ok) throw new Error(`OpenMail: ${response.status}`);

    const inbox = await response.json();
    // inbox.id      → "inb_8f3a1b2c"
    // inbox.address → "jane@openmail.sh"

    await fs.appendFile(
      containerEnvPath,
      [
        `OPENMAIL_API_KEY=${OPENMAIL_API_KEY}`,
        `OPENMAIL_INBOX_ID=${inbox.id}`,
        `OPENMAIL_ADDRESS=${inbox.address}`,
      ].join("\n") + "\n"
    );

    return inbox;
}
```

--------------------------------

### Subscribe with event replay

Source: https://docs.openmail.sh/pages/websockets/protocol

When reconnecting, include `last_event_id` to resume receiving events that occurred after a specific event. This helps prevent data loss.

```json
{ "type": "subscribe", "last_event_id": "evt_7f2a3b4c" }
```

--------------------------------

### Send Email (CLI)

Source: https://docs.openmail.sh/integrations/skill-files/api

Send an email using the OpenMail CLI. Supports plain text, HTML, attachments, and replying in threads.

```APIDOC
## Send email

### Description
Send an email using the OpenMail CLI. Supports plain text, HTML, attachments, and replying in threads.

### CLI Command
```bash
openmail send \
  --to "recipient@example.com" \
  --subject "Subject" \
  --body "Plain text body."

# Reply in thread (subject ignored)
openmail send \
  --to "recipient@example.com" \
  --thread-id "thr_..." \
  --body "Reply body."

# With HTML and attachments
openmail send \
  --to "recipient@example.com" \
  --subject "Report" \
  --body "See attached." \
  --body-html "<p>See attached.</p>" \
  --attach ./report.pdf \
  --attach ./data.csv
```

### Flags
* `--to` (required) — recipient address
* `--subject` (required unless `--thread-id` is set) — email subject
* `--body` (required) — plain text body
* `--body-html` — optional HTML body
* `--thread-id` — reply in an existing thread
* `--attach` — file path to attach (repeatable)
* `--inbox-id` — override default inbox

### Response
```json
{
  "id": "msg_...",
  "threadId": "thr_...",
  "inboxId": "inb_...",
  "direction": "outbound",
  "createdAt": "2024-01-01T00:00:00.000Z"
}
```
```

--------------------------------

### Send an Email with OpenMail API

Source: https://docs.openmail.sh/guides/api-integration

Use this endpoint to send a new email. Include an Idempotency-Key to prevent duplicate sends on retries.

```bash
curl -s -X POST "https://api.openmail.sh/v1/inboxes/$OPENMAIL_INBOX_ID/send" \
  -H "Authorization: Bearer $OPENMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Subject",
    "body": "Message body"
  }'
```

--------------------------------

### GET /v1/attachments/{messageId}/{filename}

Source: https://docs.openmail.sh/integrations/skill-files/api

Returns attachment data for a given message and filename. The signed URL for the attachment is included in the message payload and should be fetched promptly as URLs expire.

```APIDOC
## GET /v1/attachments/{messageId}/{filename}

### Description
Returns attachment data for a given message and filename. The signed URL for the attachment is included in the message payload and should be fetched promptly as URLs expire.

### Method
GET

### Endpoint
/v1/attachments/{messageId}/{filename}

### Parameters
#### Path Parameters
- **messageId** (string) - Required - The ID of the message the attachment belongs to.
- **filename** (string) - Required - The name of the attachment file.
```
Tokens:
Raw