eigenmail-sdk

TypeScript SDK for EigenMail — email for sovereign agents.

EigenMail gives autonomous AI agents their own email addresses, authenticated via Ethereum wallets using Sign-In with Ethereum (SIWE).

Install

npm install eigenmail-sdk
# or
bun add eigenmail-sdk

Quick Start

import { EigenMailClient } from "eigenmail-sdk";

const client = new EigenMailClient({
  privateKey: "0x...", // Ethereum private key
});

// Authenticate (SIWE)
await client.login();

// Send an email
await client.send({
  to: "[email protected]",
  subject: "Hello from my agent",
  body: "This email was sent by an autonomous agent.",
});

// Read inbox
const { messages } = await client.inbox();

// Read a specific message
const msg = await client.read(messages[0].id);

// Wait for an incoming email
const email = await client.waitForEmail({
  from: "[email protected]",
  subject: "verification",
  timeout: 60_000,
});

API

new EigenMailClient(opts)

| Option | Type | Default | Description | |---|---|---|---| | privateKey | `0x${string}` | required | Ethereum private key | | apiUrl | string | https://api.eigenagents.org | API base URL | | domain | string | api.eigenagents.org | SIWE domain |

Methods

| Method | Returns | Description | |---|---|---| | login() | { token, email } | Authenticate via SIWE | | me() | AgentInfo | Get current agent info | | createAgent(address) | { address, email } | Register a new agent (requires creator role) | | inbox(opts?) | { messages, total } | List inbox messages | | read(id) | MailMessageFull | Read a message by ID | | send({ to, subject, body }) | { id, from, to } | Send an email | | trash(id) | void | Delete a message | | waitForEmail(opts?) | MailMessageFull \| null | Poll until a matching email arrives | | listCreators() | CreatorInfo[] | List creator addresses (admin only) | | addCreator(address) | CreatorInfo | Add a creator (admin only) | | removeCreator(address) | void | Remove a creator (admin only) |

waitForEmail(opts?)

| Option | Type | Default | Description | |---|---|---|---| | since | Date | new Date() | Only match emails after this time | | from | string | — | Match sender (substring, case-insensitive) | | subject | string | — | Match subject (substring, case-insensitive) | | timeout | number | 120000 | Max wait time in ms | | interval | number | 5000 | Poll interval in ms |

AI Agent Tools

The SDK includes pre-built tools compatible with the Vercel AI SDK:

import { EigenMailClient, eigenMailTools } from "eigenmail-sdk";

const client = new EigenMailClient({ privateKey: "0x..." });
const tools = eigenMailTools(client, { dataDir: "./emails" });

// Use with any AI SDK-compatible framework
const result = await generateText({
  model: yourModel,
  tools,
  prompt: "Check my inbox and summarize the latest email",
});

Available tools: sendEmail, readInbox, readMessage, trashMessage, waitForEmail

The ai and zod peer dependencies are optional — only needed if you use the tools.

Error Handling

All API errors throw EigenMailError with status, detail, and path properties:

import { EigenMailError } from "eigenmail-sdk";

try {
  await client.send({ to: "bad", subject: "test", body: "test" });
} catch (e) {
  if (e instanceof EigenMailError) {
    console.error(e.status, e.detail);
  }
}

License

MIT