emailingagents

Getting started

Pick the path that matches how you work. Every path ends with the same result: an inbox, a message sent from it, and a way to see the reply. Before you start, check the feature table: it says which parts exist in the API, the dashboard, the SDKs and MCP.

All paths need an account. Sign up at /app/signup, then click the link in the verification email. Until you do, you can receive mail but not send it or create API keys (403 email_unverified).

I want toGo to
Click around, no codeDashboard only
Call HTTP from any languageREST
Use Node.js or TypeScriptTypeScript SDK
Use PythonPython SDK
Give an AI assistant mail toolsMCP

Dashboard only#

The dashboard lives at /app. It needs no key and no code.

  1. Sign in, open Inboxes, choose New inbox, enter a username (or leave it blank for a random address).
  2. Open the inbox, choose Compose, enter a recipient, subject and text, and send.
  3. Replies appear in the inbox's thread list. Open a thread to read it and reply from the box at the bottom.
  4. Use Drafts to prepare mail for review, Pods to separate customers, Allow & block and Suppressions to control who you mail, Webhooks to point events at your URL, API keys to create a key for code, Domains to generate DNS records, Billing for your plan, and Settings for your password, two-step verification, sessions and members. The Overview shows usage and delivery charts.

What works through the API but has no dashboard screen yet: forward, scheduled send, search, attachments. The availability table is the authority.

REST#

Create a key in the dashboard under API keys (the secret is shown once), then:

export BASE_URL="http://localhost:3000"   # the origin you signed up on
export API_KEY="am_..."

curl -X POST "$BASE_URL/v0/inboxes" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"username": "hello-agent"}'

Copy inbox_id from the response, then send and read:

export INBOX_ID="inbox_..."

curl -X POST "$BASE_URL/v0/inboxes/$INBOX_ID/messages/send" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"to": "you@example.com", "subject": "Hello", "text": "Sent by an agent."}'

curl "$BASE_URL/v0/inboxes/$INBOX_ID/messages?limit=10" -H "Authorization: Bearer $API_KEY"

Next: authentication, the API reference and webhooks to be told when mail arrives. Do not set Content-Type: application/json on requests without a body, such as DELETE: the server answers 400 bad_request.

TypeScript SDK#

The SDK has no dependencies and needs Node 22 or newer. It is not published to npm yet: build it from the repository's sdk/ folder and install it from there (see the SDK page).

import { EmailingAgentsClient } from "emailingagents-sdk";

const client = new EmailingAgentsClient({ apiKey: process.env.API_KEY!, baseUrl: process.env.BASE_URL! });
const inbox = await client.inboxes.create({ username: "hello-agent" });
await client.inboxes.messages.send(inbox.inbox_id, { to: "you@example.com", subject: "Hello", text: "Sent by an agent." });
const { messages } = await client.inboxes.messages.list(inbox.inbox_id, { limit: 10 });
console.log(messages.map((m) => m.subject));

Always pass baseUrl. The SDK covers inboxes, messages, threads, drafts, webhooks, pods, API keys, rates and WebSockets. It does not cover lists, suppressions, domains, search, usage metrics or sign-up: use the Python SDK or plain HTTP for those.

Python SDK#

Needs Python 3.9 or newer and httpx. Not published to PyPI yet; install from the repository's python/ folder (see the Python SDK page).

from emailingagents import Client

client = Client(api_key="am_...", base_url="http://localhost:3000")
inbox = client.inboxes.create(username="hello-agent")
client.inboxes.messages.send(inbox.inbox_id, to="you@example.com", subject="Hello", text="Sent by an agent.")
for message in client.inboxes.messages.list_all(inbox.inbox_id):
    print(message.subject)

The Python client covers the whole /v0 API, plus an async client and a LangChain toolkit.

MCP#

Use this when an AI assistant, not your own code, should read and send mail. Create an API key first; give an assistant that only needs to read a key limited to inbox_read, message_read and thread_read.

The hosted endpoint needs nothing installed:

curl -s "$BASE_URL/mcp" -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

That call lists the tools. Point an MCP client at $BASE_URL/mcp with the same Authorization header, and add ?read_only=1 to the URL to hide every tool that sends or changes data. A local stdio server is also available. See the MCP page for client configuration.

What next#

← IntroductionQuickstart →