Back to Details

agentmail

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AgentMail SDK

AgentMail SDK

AgentMail is an API-first email platform for AI agents. Install the SDK and initialize the client.
AgentMail是一款面向AI Agent的API优先的邮件平台。安装SDK并初始化客户端。

Installation

安装

bash
undefined
bash
undefined

TypeScript/Node

TypeScript/Node

npm install agentmail
npm install agentmail

Python

Python

pip install agentmail
undefined
pip install agentmail
undefined

Setup

初始化设置

typescript
import { AgentMailClient } from "agentmail";
const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });
python
from agentmail import AgentMail
client = AgentMail(api_key="YOUR_API_KEY")
typescript
import { AgentMailClient } from "agentmail";
const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });
python
from agentmail import AgentMail
client = AgentMail(api_key="YOUR_API_KEY")

Inboxes

收件箱

Create scalable inboxes on-demand. Each inbox has a unique email address.
typescript
// Create inbox (auto-generated address)
const autoInbox = await client.inboxes.create();

// Create with custom username and domain
const customInbox = await client.inboxes.create({
  username: "support",
  domain: "yourdomain.com",
});

// List, get, delete
const inboxes = await client.inboxes.list();
const fetchedInbox = await client.inboxes.get({
  inboxId: "inbox@agentmail.to",
});
await client.inboxes.delete({ inboxId: "inbox@agentmail.to" });
python
undefined
按需创建可扩展的收件箱。每个收件箱都有唯一的电子邮件地址。
typescript
// Create inbox (auto-generated address)
const autoInbox = await client.inboxes.create();

// Create with custom username and domain
const customInbox = await client.inboxes.create({
  username: "support",
  domain: "yourdomain.com",
});

// List, get, delete
const inboxes = await client.inboxes.list();
const fetchedInbox = await client.inboxes.get({
  inboxId: "inbox@agentmail.to",
});
await client.inboxes.delete({ inboxId: "inbox@agentmail.to" });
python
undefined

Create inbox (auto-generated address)

Create inbox (auto-generated address)

inbox = client.inboxes.create()
inbox = client.inboxes.create()

Create with custom username and domain

Create with custom username and domain

inbox = client.inboxes.create(username="support", domain="yourdomain.com")
inbox = client.inboxes.create(username="support", domain="yourdomain.com")

List, get, delete

List, get, delete

inboxes = client.inboxes.list() inbox = client.inboxes.get(inbox_id="inbox@agentmail.to") client.inboxes.delete(inbox_id="inbox@agentmail.to")
undefined
inboxes = client.inboxes.list() inbox = client.inboxes.get(inbox_id="inbox@agentmail.to") client.inboxes.delete(inbox_id="inbox@agentmail.to")
undefined

Messages

邮件

Always send both 
text
and 
html
for best deliverability.
typescript
// Send message
await client.inboxes.messages.send({
  inboxId: "agent@agentmail.to",
  to: "recipient@example.com",
  subject: "Hello",
  text: "Plain text version",
  html: "<p>HTML version</p>",
  labels: ["outreach"],
});

// Reply to message
await client.inboxes.messages.reply({
  inboxId: "agent@agentmail.to",
  messageId: "msg_123",
  text: "Thanks for your email!",
});

// List and get messages
const messages = await client.inboxes.messages.list({
  inboxId: "agent@agentmail.to",
});
const message = await client.inboxes.messages.get({
  inboxId: "agent@agentmail.to",
  messageId: "msg_123",
});

// Update labels
await client.inboxes.messages.update({
  inboxId: "agent@agentmail.to",
  messageId: "msg_123",
  addLabels: ["replied"],
  removeLabels: ["unreplied"],
});
python
undefined
为确保最佳送达率，请始终同时发送
text
和
html
格式内容。
typescript
// Send message
await client.inboxes.messages.send({
  inboxId: "agent@agentmail.to",
  to: "recipient@example.com",
  subject: "Hello",
  text: "Plain text version",
  html: "<p>HTML version</p>",
  labels: ["outreach"],
});

// Reply to message
await client.inboxes.messages.reply({
  inboxId: "agent@agentmail.to",
  messageId: "msg_123",
  text: "Thanks for your email!",
});

// List and get messages
const messages = await client.inboxes.messages.list({
  inboxId: "agent@agentmail.to",
});
const message = await client.inboxes.messages.get({
  inboxId: "agent@agentmail.to",
  messageId: "msg_123",
});

// Update labels
await client.inboxes.messages.update({
  inboxId: "agent@agentmail.to",
  messageId: "msg_123",
  addLabels: ["replied"],
  removeLabels: ["unreplied"],
});
python
undefined

Send message

Send message

client.inboxes.messages.send( inbox_id="agent@agentmail.to", to="recipient@example.com", subject="Hello", text="Plain text version", html="<p>HTML version</p>", labels=["outreach"] )
client.inboxes.messages.send( inbox_id="agent@agentmail.to", to="recipient@example.com", subject="Hello", text="Plain text version", html="<p>HTML version</p>", labels=["outreach"] )

Reply to message

Reply to message

client.inboxes.messages.reply( inbox_id="agent@agentmail.to", message_id="msg_123", text="Thanks for your email!" )
client.inboxes.messages.reply( inbox_id="agent@agentmail.to", message_id="msg_123", text="Thanks for your email!" )

List and get messages

List and get messages

messages = client.inboxes.messages.list(inbox_id="agent@agentmail.to") message = client.inboxes.messages.get(inbox_id="agent@agentmail.to", message_id="msg_123")
messages = client.inboxes.messages.list(inbox_id="agent@agentmail.to") message = client.inboxes.messages.get(inbox_id="agent@agentmail.to", message_id="msg_123")

Update labels

Update labels

client.inboxes.messages.update( inbox_id="agent@agentmail.to", message_id="msg_123", add_labels=["replied"], remove_labels=["unreplied"] )
undefined
client.inboxes.messages.update( inbox_id="agent@agentmail.to", message_id="msg_123", add_labels=["replied"], remove_labels=["unreplied"] )
undefined

Threads

对话线程

Threads group related messages in a conversation.
typescript
// List threads (with optional label filter)
const threads = await client.inboxes.threads.list({
  inboxId: "agent@agentmail.to",
  labels: ["unreplied"],
});

// Get thread details
const thread = await client.inboxes.threads.get({
  inboxId: "agent@agentmail.to",
  threadId: "thd_123",
});

// Org-wide thread listing
const allThreads = await client.threads.list();
python
undefined
对话线程会将对话中的相关邮件分组。
typescript
// List threads (with optional label filter)
const threads = await client.inboxes.threads.list({
  inboxId: "agent@agentmail.to",
  labels: ["unreplied"],
});

// Get thread details
const thread = await client.inboxes.threads.get({
  inboxId: "agent@agentmail.to",
  threadId: "thd_123",
});

// Org-wide thread listing
const allThreads = await client.threads.list();
python
undefined

List threads (with optional label filter)

List threads (with optional label filter)

threads = client.inboxes.threads.list(inbox_id="agent@agentmail.to", labels=["unreplied"])
threads = client.inboxes.threads.list(inbox_id="agent@agentmail.to", labels=["unreplied"])

Get thread details

Get thread details

thread = client.inboxes.threads.get(inbox_id="agent@agentmail.to", thread_id="thd_123")
thread = client.inboxes.threads.get(inbox_id="agent@agentmail.to", thread_id="thd_123")

Org-wide thread listing

Org-wide thread listing

all_threads = client.threads.list()
undefined
all_threads = client.threads.list()
undefined

Attachments

附件

Send attachments with Base64 encoding. Retrieve from messages or threads.
typescript
// Send with attachment
const content = Buffer.from(fileBytes).toString("base64");
await client.inboxes.messages.send({
  inboxId: "agent@agentmail.to",
  to: "recipient@example.com",
  subject: "Report",
  text: "See attached.",
  attachments: [
    { content, filename: "report.pdf", contentType: "application/pdf" },
  ],
});

// Get attachment
const fileData = await client.inboxes.messages.getAttachment({
  inboxId: "agent@agentmail.to",
  messageId: "msg_123",
  attachmentId: "att_456",
});
python
import base64
使用Base64编码发送附件。可从邮件或对话线程中获取附件。
typescript
// Send with attachment
const content = Buffer.from(fileBytes).toString("base64");
await client.inboxes.messages.send({
  inboxId: "agent@agentmail.to",
  to: "recipient@example.com",
  subject: "Report",
  text: "See attached.",
  attachments: [
    { content, filename: "report.pdf", contentType: "application/pdf" },
  ],
});

// Get attachment
const fileData = await client.inboxes.messages.getAttachment({
  inboxId: "agent@agentmail.to",
  messageId: "msg_123",
  attachmentId: "att_456",
});
python
import base64

Send with attachment

Send with attachment

content = base64.b64encode(file_bytes).decode() client.inboxes.messages.send( inbox_id="agent@agentmail.to", to="recipient@example.com", subject="Report", text="See attached.", attachments=[{"content": content, "filename": "report.pdf", "content_type": "application/pdf"}] )
content = base64.b64encode(file_bytes).decode() client.inboxes.messages.send( inbox_id="agent@agentmail.to", to="recipient@example.com", subject="Report", text="See attached.", attachments=[{"content": content, "filename": "report.pdf", "content_type": "application/pdf"}] )

Get attachment

Get attachment

file_data = client.inboxes.messages.get_attachment( inbox_id="agent@agentmail.to", message_id="msg_123", attachment_id="att_456" )
undefined
file_data = client.inboxes.messages.get_attachment( inbox_id="agent@agentmail.to", message_id="msg_123", attachment_id="att_456" )
undefined

Drafts

草稿

Create drafts for human-in-the-loop approval before sending.
typescript
// Create draft
const draft = await client.inboxes.drafts.create({
  inboxId: "agent@agentmail.to",
  to: "recipient@example.com",
  subject: "Pending approval",
  text: "Draft content",
});

// Send draft (converts to message)
await client.inboxes.drafts.send({
  inboxId: "agent@agentmail.to",
  draftId: draft.draftId,
});
python
undefined
创建草稿，供人工审核通过后再发送。
typescript
// Create draft
const draft = await client.inboxes.drafts.create({
  inboxId: "agent@agentmail.to",
  to: "recipient@example.com",
  subject: "Pending approval",
  text: "Draft content",
});

// Send draft (converts to message)
await client.inboxes.drafts.send({
  inboxId: "agent@agentmail.to",
  draftId: draft.draftId,
});
python
undefined

Create draft

Create draft

draft = client.inboxes.drafts.create( inbox_id="agent@agentmail.to", to="recipient@example.com", subject="Pending approval", text="Draft content" )
draft = client.inboxes.drafts.create( inbox_id="agent@agentmail.to", to="recipient@example.com", subject="Pending approval", text="Draft content" )

Send draft (converts to message)

Send draft (converts to message)

client.inboxes.drafts.send(inbox_id="agent@agentmail.to", draft_id=draft.draft_id)
undefined
client.inboxes.drafts.send(inbox_id="agent@agentmail.to", draft_id=draft.draft_id)
undefined

Pods

Pod

Multi-tenant isolation for SaaS platforms. Each customer gets isolated inboxes.
typescript
// Create pod for a customer
const pod = await client.pods.create({ clientId: "customer_123" });

// Create inbox within pod
const inbox = await client.inboxes.create({ podId: pod.podId });

// List resources scoped to pod
const inboxes = await client.inboxes.list({ podId: pod.podId });
python
undefined
为SaaS平台提供多租户隔离功能。每个客户都拥有独立的收件箱。
typescript
// Create pod for a customer
const pod = await client.pods.create({ clientId: "customer_123" });

// Create inbox within pod
const inbox = await client.inboxes.create({ podId: pod.podId });

// List resources scoped to pod
const inboxes = await client.inboxes.list({ podId: pod.podId });
python
undefined

Create pod for a customer

Create pod for a customer

pod = client.pods.create(client_id="customer_123")
pod = client.pods.create(client_id="customer_123")

Create inbox within pod

Create inbox within pod

inbox = client.inboxes.create(pod_id=pod.pod_id)
inbox = client.inboxes.create(pod_id=pod.pod_id)

List resources scoped to pod

List resources scoped to pod

inboxes = client.inboxes.list(pod_id=pod.pod_id)
undefined
inboxes = client.inboxes.list(pod_id=pod.pod_id)
undefined

Idempotency

幂等性

Use 
clientId
for safe retries on create operations.
typescript
const inbox = await client.inboxes.create({
  clientId: "unique-idempotency-key",
});
// Retrying with same clientId returns the original inbox, not a duplicate
python
inbox = client.inboxes.create(client_id="unique-idempotency-key")
在创建操作中使用
clientId
以实现安全重试。
typescript
const inbox = await client.inboxes.create({
  clientId: "unique-idempotency-key",
});
// Retrying with same clientId returns the original inbox, not a duplicate
python
inbox = client.inboxes.create(client_id="unique-idempotency-key")

Retrying with same client_id returns the original inbox, not a duplicate

Retrying with same client_id returns the original inbox, not a duplicate

undefined
undefined

Real-Time Events

实时事件

For real-time notifications, see the reference files:
  • webhooks.md - HTTP-based notifications (requires public URL)
  • websockets.md - Persistent connection (no public URL needed)
如需实时通知，请查看参考文档：
  • webhooks.md - 基于HTTP的通知（需要公网URL）
  • websockets.md - 持久化连接（无需公网URL）