myagentmail

TypeScript SDK for the myagentmail API — email infrastructure for AI agents.

For Claude Desktop / Cursor, see myagentmail-mcp.

Install

npm install myagentmail

Quick start

import { MyAgentMail } from "myagentmail";

const client = new MyAgentMail({ apiKey: process.env.MYAGENTMAIL_KEY! });

// Create an inbox
const inbox = await client.inboxes.create({
  username: "scout",
  displayName: "Scout",
});
console.log("Inbox:", inbox.email);
console.log("IMAP password:", inbox.imapPassword); // only shown once

// Send an email
const sent = await client.messages.send(inbox.id, {
  to: "[email protected]",
  subject: "Quick question",
  plainBody: "Hi — do you have time to chat this week?",
  verified: true,
});
console.log("Sent:", sent.id, "Thread:", sent.threadId);

// List inbound messages
const { messages } = await client.messages.list(inbox.id, {
  direction: "inbound",
  limit: 10,
});
for (const m of messages) {
  console.log(`${m.from}: ${m.subject}`);
}

// Reply in-thread
if (messages.length > 0) {
  await client.messages.reply(inbox.id, messages[0].id, {
    plainBody: "Thanks — scheduling that call now.",
  });
}

Resources

client.inboxes

client.inboxes.create({ username?, displayName?, domain?, workspaceId? })
client.inboxes.list({ workspace? })
client.inboxes.get(inboxId)
client.inboxes.update(inboxId, { displayName?, metadata? })
client.inboxes.delete(inboxId)
client.inboxes.addAddress(inboxId, { email, primary? })
client.inboxes.removeAddress(inboxId, address)

client.messages

client.messages.send(inboxId, { to, subject, plainBody?, htmlBody?, verified? })
client.messages.reply(inboxId, messageId, { plainBody?, htmlBody? })
client.messages.replyAll(inboxId, messageId, { plainBody?, htmlBody? })
client.messages.forward(inboxId, messageId, { to, plainBody?, subject? })
client.messages.list(inboxId, { direction?, limit?, offset? })
client.messages.get(inboxId, messageId)
client.messages.markRead(inboxId, messageId, isRead)
client.messages.delete(inboxId, messageId)
client.messages.listAttachments(inboxId, messageId)
client.messages.downloadAttachment(inboxId, messageId, attachmentId)
client.messages.downloadRaw(inboxId, messageId)

client.threads

client.threads.list(inboxId, { limit?, offset? })
client.threads.get(inboxId, threadId)

client.drafts

client.drafts.create(inboxId, { to?, subject?, plainBody?, replyToMessageId? })
client.drafts.list(inboxId, { limit? })
client.drafts.get(inboxId, draftId)
client.drafts.update(inboxId, draftId, { to?, subject?, plainBody? })
client.drafts.delete(inboxId, draftId)
client.drafts.send(inboxId, draftId) // sends + deletes atomically

client.lists

client.lists.create(inboxId, { name, description? })
client.lists.list(inboxId)
client.lists.get(inboxId, listId)
client.lists.delete(inboxId, listId)
client.lists.addEntry(inboxId, listId, { email, displayName?, metadata? })
client.lists.removeEntry(inboxId, listId, entryId)

client.domains

client.domains.create({ domain, workspaceId? })
client.domains.list({ workspace? })
client.domains.get(domain)
client.domains.verify(domain)
client.domains.zoneFile(domain) // returns BIND-format text
client.domains.delete(domain)

client.workspaces

client.workspaces.create({ name, slug? })
client.workspaces.list()
client.workspaces.get(workspaceId)
client.workspaces.delete(workspaceId)
client.workspaces.createKey(workspaceId, { name? })
client.workspaces.listKeys(workspaceId)
client.workspaces.revokeKey(workspaceId, keyId)

client.webhooks

client.webhooks.create({ url, events })
client.webhooks.list()
client.webhooks.get(webhookId)
client.webhooks.update(webhookId, { url?, events?, isActive? })
client.webhooks.delete(webhookId)

Utilities

client.verifyEmail({ email?, emails? })
client.metrics({ from?, to?, workspace?, inbox? })

Error handling

import { MyAgentMailError } from "myagentmail";

try {
  await client.messages.send(inboxId, { to: "bad", subject: "x", plainBody: "y" });
} catch (err) {
  if (err instanceof MyAgentMailError) {
    console.log(err.status); // 400
    console.log(err.code);   // "VALIDATION_ERROR"
    console.log(err.message);
  }
}

API keys

| Prefix | Scope | |---|---| | tk_ | Tenant master — every workspace | | wk_ | Workspace master — one workspace | | ak_ | Inbox scoped — one inbox |

Use the narrowest key that fits. For production agent runtimes, prefer ak_.

Links

• API Reference (interactive, OpenAPI-powered)
• Knowledge Base (concepts + guides)
• Blog
• MCP Server (for Claude Desktop / Cursor)
• OpenAPI spec

License

MIT