AgentMail SDK

# TypeScript/Node
npm install agentmail

# Python
pip install agentmail

import { AgentMailClient } from "agentmail";

const apiKey = process.env.AGENTMAIL_API_KEY;
if (!apiKey) throw new Error("Set AGENTMAIL_API_KEY in the environment");
const client = new AgentMailClient({ apiKey });

import os
from agentmail import AgentMail

api_key = os.environ.get("AGENTMAIL_API_KEY")
if not api_key:
    raise ValueError("Set AGENTMAIL_API_KEY in the environment")
client = AgentMail(api_key=api_key)

// 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" });

# Create inbox (auto-generated address)
inbox = client.inboxes.create()

# Create with custom username and domain
inbox = client.inboxes.create(username="support", domain="yourdomain.com")

# List, get, delete
inboxes = client.inboxes.list()
inbox = client.inboxes.get(inbox_id="inbox@agentmail.to")
client.inboxes.delete(inbox_id="inbox@agentmail.to")

// Send message and verify
const sent = 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"],
});
// sent.messageId confirms the message was accepted
console.log("Sent message ID:", sent.messageId);

// 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"],
});

# Send message and verify
sent = 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"]
)
# sent.message_id confirms the message was accepted
print("Sent message ID:", sent.message_id)

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

# 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")

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

// 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();

# List threads (with optional label filter)
threads = client.inboxes.threads.list(inbox_id="agent@agentmail.to", labels=["unreplied"])

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

# Org-wide thread listing
all_threads = client.threads.list()

// 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",
});

import base64

# 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"}]
)

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

// 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,
});

# Create draft
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)
client.inboxes.drafts.send(inbox_id="agent@agentmail.to", draft_id=draft.draft_id)

// 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 });

# Create pod for a customer
pod = client.pods.create(client_id="customer_123")

# Create inbox within pod
inbox = client.inboxes.create(pod_id=pod.pod_id)

# List resources scoped to pod
inboxes = client.inboxes.list(pod_id=pod.pod_id)

const inbox = await client.inboxes.create({
  clientId: "unique-idempotency-key",
});
// Retrying with same clientId returns the original inbox, not a duplicate

inbox = client.inboxes.create(client_id="unique-idempotency-key")
# Retrying with same client_id returns the original inbox, not a duplicate

// Step 1: Create inbox and verify it exists
const inbox = await client.inboxes.create({ username: "agent", domain: "yourdomain.com" });
// Verify: inbox.inboxId must be present before sending
if (!inbox.inboxId) throw new Error("Inbox creation failed");

// Step 2: Send a message and confirm acceptance
const sent = await client.inboxes.messages.send({
  inboxId: inbox.inboxId,
  to: "recipient@example.com",
  subject: "Hello",
  text: "Plain text version",
  html: "<p>HTML version</p>",
});
// Verify: sent.messageId confirms the API accepted the message
if (!sent.messageId) throw new Error("Message send failed");
console.log("Delivered message ID:", sent.messageId);

// Step 3: Confirm the message is retrievable
const message = await client.inboxes.messages.get({
  inboxId: inbox.inboxId,
  messageId: sent.messageId,
});
console.log("Confirmed message subject:", message.subject);

# Step 1: Create inbox and verify it exists
inbox = client.inboxes.create(username="agent", domain="yourdomain.com")
# Verify: inbox.inbox_id must be present before sending
if not inbox.inbox_id:
    raise ValueError("Inbox creation failed")

# Step 2: Send a message and confirm acceptance
sent = client.inboxes.messages.send(
    inbox_id=inbox.inbox_id,
    to="recipient@example.com",
    subject="Hello",
    text="Plain text version",
    html="<p>HTML version</p>",
)
# Verify: sent.message_id confirms the API accepted the message
if not sent.message_id:
    raise ValueError("Message send failed")
print("Delivered message ID:", sent.message_id)

# Step 3: Confirm the message is retrievable
message = client.inboxes.messages.get(
    inbox_id=inbox.inbox_id,
    message_id=sent.message_id,
)
print("Confirmed message subject:", message.subject)

const inboxIds = ["agent1@agentmail.to", "agent2@agentmail.to", "agent3@agentmail.to"];
const results = { succeeded: [] as string[], failed: [] as string[] };

for (const inboxId of inboxIds) {
  try {
    const sent = await client.inboxes.messages.send({
      inboxId,
      to: "recipient@example.com",
      subject: "Batch update",
      text: "Message body",
    });
    results.succeeded.push(sent.messageId);
  } catch (error) {
    // Log and continue — one failure should not abort remaining sends
    console.error(`Failed for ${inboxId}:`, error.message);
    results.failed.push(inboxId);
  }
}
console.log(`Sent: ${results.succeeded.length}, Failed: ${results.failed.length}`);
// Retry failed inboxes separately, using clientId for idempotency if needed

from agentmail import AgentMailError

inbox_ids = ["agent1@agentmail.to", "agent2@agentmail.to", "agent3@agentmail.to"]
succeeded, failed = [], []

for inbox_id in inbox_ids:
    try:
        sent = client.inboxes.messages.send(
            inbox_id=inbox_id,
            to="recipient@example.com",
            subject="Batch update",
            text="Message body",
        )
        succeeded.append(sent.message_id)
    except AgentMailError as e:
        # Log and continue — one failure should not abort remaining sends
        print(f"Failed for {inbox_id}: {e}")
        failed.append(inbox_id)

print(f"Sent: {len(succeeded)}, Failed: {len(failed)}")
# Retry failed inboxes separately, using client_id for idempotency if needed

try {
  const sent = await client.inboxes.messages.send({
    inboxId: "agent@agentmail.to",
    to: "recipient@example.com",
    subject: "Hello",
    text: "Plain text version",
    html: "<p>HTML version</p>",
  });
  console.log("Sent message ID:", sent.messageId);
} catch (error) {
  // Inspect error.status for HTTP status codes (e.g. 404 = inbox not found, 422 = validation error)
  console.error("Send failed:", error.message);
}

try {
  const message = await client.inboxes.messages.get({
    inboxId: "agent@agentmail.to",
    messageId: "msg_123",
  });
} catch (error) {
  // 404 indicates the message or inbox does not exist
  console.error("Fetch failed:", error.message);
}

from agentmail import AgentMailError

try:
    sent = client.inboxes.messages.send(
        inbox_id="agent@agentmail.to",
        to="recipient@example.com",
        subject="Hello",
        text="Plain text version",
        html="<p>HTML version</p>",
    )
    print("Sent message ID:", sent.message_id)
except AgentMailError as e:
    # e.status_code for HTTP status (e.g. 404 = inbox not found, 422 = validation error)
    print("Send failed:", e)

try:
    message = client.inboxes.messages.get(
        inbox_id="agent@agentmail.to",
        message_id="msg_123"
    )
except AgentMailError as e:
    # 404 indicates the message or inbox does not exist
    print("Fetch failed:", e)