> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailchannels.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send email from OpenClaw agents using MailChannels

> Configure an OpenClaw AI agent to send and track email through MailChannels, with a dedicated inbox via AgentMail for inbound replies.

[OpenClaw](https://github.com/openclaw/openclaw) is an open-source AI agent framework that lets you build and run autonomous agents capable of executing tools and skills. One of the most common needs when running an agent is the ability to send email — for notifications, outreach, confirmations, and follow-ups. This guide walks you through connecting OpenClaw to the MailChannels Email API for outbound sending and delivery tracking, and optionally to AgentMail for giving your agent its own dedicated inbox.

## How the pieces fit together

* **OpenClaw** runs your agent and handles tool and skill execution.
* **MailChannels Email API** handles sending email and reports delivery events (delivered, bounced, dropped) back to your agent via webhooks.
* **AgentMail** (optional, but recommended) gives your agent a dedicated inbox — separate from your personal email — with support for real-time events and reply handling.

Each piece does one job, and your agent only gets the permissions it actually needs.

## What you need before you start

* A self-hosted OpenClaw installation.
* MailChannels Email API credentials: `MAILCHANNELS_API_KEY` and `MAILCHANNELS_ACCOUNT_ID` (your customer handle).
* DNS access for the domain you plan to send from.
* Optionally: a public HTTPS endpoint where MailChannels can POST delivery webhooks.

## Setting up the integration

<Steps>
  <Step title="Set up your MailChannels credentials">
    The MailChannels skill for OpenClaw reads two environment variables:

    * `MAILCHANNELS_API_KEY` — sent in the `X-Api-Key` header on every request.
    * `MAILCHANNELS_ACCOUNT_ID` — your customer handle, visible in the [MailChannels Console](https://console.mailchannels.net).

    There is also an optional override if you need a different base URL:

    * `MAILCHANNELS_BASE_URL` — defaults to `https://api.mailchannels.net/tx/v1`.

    Export them in your shell before launching OpenClaw:

    ```bash theme={null}
    export MAILCHANNELS_API_KEY="YOUR_API_KEY"
    export MAILCHANNELS_ACCOUNT_ID="YOUR_ACCOUNT_ID"
    # Optional:
    export MAILCHANNELS_BASE_URL="https://api.mailchannels.net/tx/v1"
    ```
  </Step>

  <Step title="Lock down your sending domain">
    Before letting your agent send email from your domain, configure **Domain Lockdown** via a DNS TXT record. This ensures only your MailChannels account can send as that domain.

    For each domain you plan to send from, add a TXT record:

    | Field     | Value                           |
    | --------- | ------------------------------- |
    | **Host**  | `_mailchannels.<your-domain>`   |
    | **Value** | `v=mc1; auid=<YOUR_ACCOUNT_ID>` |

    After adding the record, you can verify your full domain configuration (DKIM, SPF, and Domain Lockdown) using the `POST /check-domain` endpoint.

    <Note>
      Your domain should also have a valid SPF record that authorizes MailChannels as a sender. Without SPF, deliverability will be poor and some receiving servers will reject your mail.
    </Note>
  </Step>

  <Step title="Install the MailChannels skill in OpenClaw">
    The MailChannels integration is published as an OpenClaw skill called `mailchannels-email-api`. Install it with:

    ```bash theme={null}
    npx openclaw add @ttulttul/mailchannels
    ```

    This skill handles two things: sending email through the MailChannels API, and ingesting signed delivery-event webhooks into your OpenClaw environment.
  </Step>

  <Step title="Send your first email">
    MailChannels exposes a `POST /send` endpoint. The minimum payload requires four fields: `personalizations` (who you are sending to), `from`, `subject`, and `content`.

    Here is a `curl` example showing what happens under the hood:

    ```bash theme={null}
    curl -sS -X POST "$MAILCHANNELS_BASE_URL/send" \
      -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "personalizations": [
          { "to": [ { "email": "you@example.com" } ] }
        ],
        "from": { "email": "agent@your-domain.com", "name": "OpenClaw Agent" },
        "subject": "Hello from OpenClaw via MailChannels",
        "content": [
          { "type": "text/plain", "value": "This email was sent by my agent using the MailChannels Email API." }
        ]
      }'
    ```

    Once the skill is installed and your environment variables are set, you can skip `curl` entirely and just instruct your agent:

    > Send an email to me using MailChannels with the subject "Test" and a one-line body confirming it worked.

    The agent takes it from there.
  </Step>

  <Step title="Use async sending for agent workflows">
    In agent workflows, you usually do not want your agent blocking while an email is processed — especially when sending to multiple recipients.

    Use `POST /send-async` instead of `POST /send`. This endpoint queues the message and returns immediately with a request ID. Delivery events still arrive via webhooks, so your agent retains full visibility and can move on to its next task without waiting.
  </Step>

  <Step title="Close the loop with delivery webhooks">
    Sending is only half the story. A genuinely useful agent can also answer: Did it deliver? Did it bounce? Should I retry or suppress that recipient?

    **Register a webhook endpoint**

    Use the following endpoints to manage your webhook subscriptions:

    | Endpoint                  | Description                          |
    | ------------------------- | ------------------------------------ |
    | `POST /webhook`           | Enroll for webhook notifications     |
    | `GET /webhook`            | Retrieve enrolled webhooks           |
    | `DELETE /webhook`         | Remove webhooks you no longer need   |
    | `POST /webhook/validate`  | Test that your endpoint is reachable |
    | `GET /webhook/public-key` | Retrieve the webhook signing key     |

    **Verify webhook signatures**

    MailChannels signs every delivery-event webhook. Incoming requests include three headers: `Content-Digest`, `Signature-Input`, and `Signature`.

    To verify them:

    1. Parse `Signature-Input` — it includes `created`, `alg`, and `keyid`.
    2. Reject anything with a stale timestamp.
    3. Fetch the public key for the given `keyid` using `GET /webhook/public-key`.
    4. Verify the Ed25519 signature per RFC 9421.

    **Correlate events back to your agent's actions**

    Webhook payloads include `email`, `customer_handle`, `timestamp`, `event`, and `request_id`. Persist the `request_id` from each send call so you can match it to delivery events and build a clean state machine: processed → delivered, soft-bounced, hard-bounced, or dropped.

    This is what lets your agent make smart decisions — retry on a soft bounce, suppress on a hard bounce, escalate on repeated failures.
  </Step>

  <Step title="Give your agent an inbox with AgentMail">
    Everything above handles outbound email. Agents often also need to *receive* messages — replies, confirmations, OTP codes, inbound support requests.

    **AgentMail** is an API-first inbox provider built specifically for AI agents. Install the official OpenClaw integration with either:

    ```bash theme={null}
    openclaw skills install agentmail-to/agentmail-skills/agentmail
    ```

    or via the ClawHub CLI:

    ```bash theme={null}
    npx clawhub@latest install agentmail
    ```

    Then add your AgentMail API key to `~/.openclaw/openclaw.json`:

    ```json theme={null}
    {
      "skills": {
        "entries": {
          "agentmail": {
            "enabled": true,
            "env": {
              "AGENTMAIL_API_KEY": "your-api-key-here"
            }
          }
        }
      }
    }
    ```

    AgentMail supports programmatic inbox creation, including custom domains. Once configured, your agent can receive replies in a dedicated inbox, search and triage messages, and trigger workflows from inbound email — all without touching your personal mailbox.
  </Step>
</Steps>

## Ideas for what to build next

With MailChannels handling outbound and AgentMail handling inbound, your OpenClaw agent is ready for workflows that feel hands-free but stay operationally sound:

* **Daily briefings** — Your agent compiles calendar items, tasks, and news into a single email, sends it via MailChannels, and tracks delivery.
* **Support triage** — Inbound email arrives at AgentMail, the agent labels and routes it, then sends a reply (or drafts one for your approval) through MailChannels.
* **Deliverability-aware automation** — If a recipient hard-bounces, the agent automatically adds them to the suppression list and notifies your ops team.

## API quick reference

**Base URL:** `https://api.mailchannels.net/tx/v1`

| Category    | Endpoint                                         | Description                           |
| ----------- | ------------------------------------------------ | ------------------------------------- |
| Sending     | `POST /send`                                     | Send an email synchronously           |
| Sending     | `POST /send-async`                               | Queue an email and return immediately |
| Webhooks    | `POST /webhook`                                  | Enroll for webhook notifications      |
| Webhooks    | `GET /webhook`                                   | Retrieve enrolled webhooks            |
| Webhooks    | `DELETE /webhook`                                | Delete webhooks                       |
| Webhooks    | `POST /webhook/validate`                         | Test your webhook endpoint            |
| Webhooks    | `GET /webhook/public-key`                        | Retrieve the webhook signing key      |
| Domains     | `POST /check-domain`                             | Check DKIM, SPF, and Domain Lockdown  |
| Usage       | `GET /usage`                                     | Retrieve account usage stats          |
| Suppression | `POST /suppression-list`                         | Add suppression entries               |
| Suppression | `GET /suppression-list`                          | Retrieve the suppression list         |
| Suppression | `DELETE /suppression-list/recipients/:recipient` | Remove a suppression entry            |