io.github.R1ghtHereWaiting/engagelab-email
Send, receive, monitor and reply to email from AI agents with threaded inbox context.
Open source Open in the app JSON README (API)
About
Send, receive, monitor and reply to email from AI agents with threaded inbox context.
Details
- Kind
- MCP servers
- Topic
- Communication
- Publisher
- r1ghtherewaiting
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.2
- Last push
- 2026-09-01T09:32:13Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-09-01 04:00:06
- Updated
- 2026-09-01 04:00:06
- Origin id
io.github.R1ghtHereWaiting/engagelab-email
README
# EngageLab Agent Email MCP Server
[](https://www.npmjs.com/package/@engagelabemail/mcp)
[](LICENSE)
[](https://nodejs.org)
**English** | [简体中文](README.zh-CN.md)
> Official EngageLab Email project.
**Send, receive, and reply to email from AI agents** — through the [Model Context Protocol](https://modelcontextprotocol.io).
Each agent gets its **own mailbox**: a real address that sends *and* receives, with conversations grouped into threads so your agent has context. Works with Claude Desktop, Claude Code, Cursor, Cowork, and any MCP-compatible client.
```json
{
"mcpServers": {
"engagelab-email": {
"command": "npx",
"args": ["-y", "@engagelabemail/mcp"],
"env": { "ENGAGELAB_EMAIL_SECRET_KEY": "sk_sg_your_key" }
}
}
}
```
## Why
Most email APIs are send-only. Agents that need to *have a conversation* over email — support, scheduling, approvals — need an inbox.
- **Send & receive** — the agent owns a dedicated mailbox, not a bolted-on parse webhook
- **Thread-aware** — replies group into conversations, so the agent sees full history
- **Sandbox mode** — test agent flows without emailing real humans
- **One env var** — no OAuth dance for local use; region inferred from the key
## Tools
| | Tool | What it does |
|---|---|---|
| **Discover** | `list_mailboxes` | List mailboxes; call this first to get IDs |
| **Send** | `send_email` | New email (text/html, cc/bcc, attachments, sandbox) |
| | `reply_email` | Reply to a message — recipients & thread inferred |
| **Receive** | `list_inbound_messages` | Inbound mail, filter by mailbox/keyword |
| | `get_message` | Full message details by UID |
| | `check_new_messages` | One-shot poll for new mail |
| **Threads** | `list_threads` / `get_thread` / `list_thread_messages` | Browse conversations |
## Quickstart
### Smithery / MCPB
For local stdio distribution, build an MCPB bundle:
```bash
npm run build:mcpb
```
The bundle is generated at `dist/engagelab-agent-email.mcpb` and can be uploaded through [Smithery publishing](https://smithery.ai/new).
### Official MCP Registry
EngageLab Agent Email is also listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.R1ghtHereWaiting%2Fengagelab-email). Clients that consume the Registry can find it by the server name `io.github.R1ghtHereWaiting/engagelab-email`; the underlying npm package remains [`@engagelabemail/mcp`](https://www.npmjs.com/package/@engagelabemail/mcp).
**1. Get a Secret Key.** Create an EngageLab account and generate a key from the console (format `sk_sg_xxx` — the prefix selects the region). Or use the [CLI](https://github.com/Metaverse-Cloud/engagelab-email-cli): `engagelab-email-cli login` creates one via browser.
**2. Create a mailbox.** In the console, create a mailbox for your agent (shared subdomain is instant; custom domains need DNS verification). Programmatic mailbox creation is on the roadmap — see [Troubleshooting](#troubleshooting) if `list_mailboxes` returns empty.
**3. Register the server.**
Claude Desktop — add the JSON block above to `claude_desktop_config.json`.
Claude Code:
```bash
claude mcp add engagelab-email \
-e ENGAGELAB_EMAIL_SECRET_KEY=sk_sg_your_key \
-- npx -y @engagelabemail/mcp
```
Then ask your agent:
> List my mailboxes, then send an email from the first one to bob@example.com saying the invoice is approved.
A typical agent loop for a support bot:
```
check_new_messages() → [messageUids]
get_message(uid) → body, attachments
list_thread_messages(threadId) → full conversation context
reply_email(uid, { text: ... }) → response lands in the same thread
```
## Configuration
| Environment variable | Required | Description |
|---|---|---|
| `ENGAGELAB_EMAIL_SECRET_KEY` | Yes | Secret Key starting with `sk_` |
| `ENGAGELAB_EMAIL_BASE_URL` | No | Override the API base URL. Inferred from the key region: `sg` → Singapore, `tr` → Türkiye |
Limits: up to 10 attachments / 10MB total per message (base64-encoded in the tool schema).
## Troubleshooting
- **`list_mailboxes` returns an empty list** — your account has no mailbox yet. Create one in the EngageLab console (see Quickstart step 2). Agents cannot self-provision mailboxes yet.
- **401 / `code 100101`** — the Secret Key is wrong or revoked. Check `ENGAGELAB_EMAIL_SECRET_KEY` and that the key's region prefix (`sk_sg_` / `sk_tr_`) matches the endpoint you use.
- **Could not determine API base URL** — the key's region prefix isn't recognized. Set `ENGAGELAB_EMAIL_BASE_URL` explicitly.
- **Reply shows up as a new conversation** — use `reply_email` (not `send_email`) so In-Reply-To headers and threading stay intact.
## Roadmap
- [ ] Hosted MCP (OAuth) for zero-config remote use
- [ ] Programmatic mailbox creation via Secret Key
- [ ] Webhook push (no polling) for `check_new_messages`
- [ ] URL-based attachment references (no base64 in context)
## Run from source
```bash
git clone https://github.com/Metaverse-Cloud/engagelab-email-mcp
cd engagelab-email-mcp
npm install && npm run build
ENGAGELAB_EMAIL_SECRET_KEY=sk_sg_xxx node dist/index.cjs
```
## Related
- [EngageLab Agent Email CLI](https://github.com/Metaverse-Cloud/engagelab-email-cli) — same mailboxes from the terminal, `--json` output for agents
- [EngageLab Node SDK](https://github.com/Metaverse-Cloud/engagelab-email-node) / [Python SDK](https://github.com/Metaverse-Cloud/engagelab-email-python) — send email from code
## License
[MIT](LICENSE)