Ordian Mail

Email API for AI agents, paid with USDC on Base via the x402 protocol.

No API keys. No accounts. Your wallet is your identity.

Install

npm install ordian-mail viem

Quick Start

import { OrdianMail } from "ordian-mail";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";
import { publicActions } from "viem";

const signer = createWalletClient({
  account: privateKeyToAccount("0x..."),
  chain: base,
  transport: http(),
}).extend(publicActions);

const mail = new OrdianMail({
  signer,
  baseUrl: "https://mail-api.ordian.ai",
});

// Create an inbox ($0.10)
const { data: inbox } = await mail.inboxes.create({
  display_name: "My Agent",
  username: "support",        // → [email protected]
});

// Send an email ($0.01)
await mail.messages.send({
  inbox_id: inbox.id,
  to: "[email protected]",
  subject: "Hello from my agent",
  text: "Plain text body",
  markdown: "# Hello\n\nThis email was sent by an AI agent.",
});

Pricing

USDC on Base. Paid per request.

| Action | Price | |--------|-------| | Create inbox | $0.10 | | Send email | $0.01 | | List messages | $0.002 | | Read message | $0.002 | | Register webhook | $0.05 | | Renew inbox | $0.05 | | Register domain | $1.00 |

What's included

• Inboxes — Create, list, renew, delete. Optional custom username.
• Send — Plain text, HTML, or Markdown. CC/BCC. Attachments.
• Receive — Inbound emails stored and queryable. Webhook notifications.
• Threads — Automatic threading via Message-ID/In-Reply-To. Filter by thread.
• Custom Domains — Bring your own domain with DNS verification and DKIM.
• Webhooks — message.received, inbox.expiring, inbox.expired.
• Bounce handling — Automatic bounce tracking and suppression.

How payments work

The SDK handles x402 payments automatically. Each paywalled request:

1. Gets a 402 response with payment details
2. Signs a USDC authorization with your wallet
3. Retries with the payment attached

API

Inboxes

// Create
const { data, error } = await mail.inboxes.create({
  display_name: "My Agent",
  username: "hello",              // optional
  domain_id: "uuid",              // optional, use a verified custom domain
  metadata: { role: "support" },  // optional
});

// List (filtered by wallet)
const { data } = await mail.inboxes.list({ limit: 10 });

// List messages
const { data } = await mail.inboxes.listMessages(inboxId, {
  thread_id: "uuid",  // optional
});

// Renew (extend expiry by 30 days)
const { data } = await mail.inboxes.renew(inboxId);

// Delete
const { data } = await mail.inboxes.delete(inboxId);

Messages

// Send
const { data } = await mail.messages.send({
  inbox_id: "uuid",
  to: "[email protected]",          // or ["[email protected]", "[email protected]"]
  cc: ["[email protected]"],               // optional
  bcc: ["[email protected]"],             // optional
  subject: "Hello",
  text: "Plain text body",
  markdown: "# Hello\n\nMarkdown body", // optional, rendered to HTML
  html: "<h1>Hello</h1>",               // optional, overrides markdown
  in_reply_to: "<message-id>",          // optional, for threading
});

// Read
const { data } = await mail.messages.read(messageId);

// Delivery status
const { data } = await mail.messages.deliveryStatus(messageId);

Custom Domains

// Register (returns DNS records to configure)
const { data } = await mail.domains.create({ domain: "mycompany.com" });

// Verify DNS
const { data } = await mail.domains.verify(domainId);

// List
const { data } = await mail.domains.list();

Webhooks

// Register
const { data } = await mail.webhooks.create({
  inbox_id: "uuid",
  url: "https://your-server.com/webhook",
  events: ["message.received", "inbox.expiring"],
});

// List deliveries
const { data } = await mail.webhooks.deliveries(webhookId);

CLI

A companion CLI is available as ordian-mail-cli:

npx ordian-mail-cli inbox create --name "My Agent" --username "hello"
npx ordian-mail-cli send --inbox <id> --to [email protected] --subject "Hi" --text "Hello"

License

MIT