Sendook

Sendook Email SDK

Open-source email infrastructure for AI agents — instant inbox creation, sending/receiving, webhooks, custom domains, and more.

Quick Start

npm install @sendook/node

import Sendook from "@sendook/node";

const client = new Sendook(process.env.SENDOOK_API_KEY);

// Create an inbox
const inbox = await client.inbox.create({
  name: "support",
  email: "support@yourdomain.com",
});

// Send an email
await client.inbox.message.send({
  inboxId: inbox.id,
  to: ["user@example.com"],
  subject: "Welcome!",
  text: "Thanks for signing up.",
});

# Create an inbox
curl -X POST https://api.sendook.com/v1/inboxes \
  -H "Authorization: Bearer $SENDOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "support", "email": "support@yourdomain.com"}'

# Send an email
curl -X POST https://api.sendook.com/v1/inboxes/{inbox_id}/messages/send \
  -H "Authorization: Bearer $SENDOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": ["user@example.com"], "subject": "Welcome!", "text": "Thanks for signing up."}'

Resource Hierarchy

Organization
└── Inbox
    ├── Thread
    │   └── Message
    │       └── Attachment
    ├── Domain
    ├── Webhook
    └── API Key

• Organization — Top-level account, owns all resources
• Inbox — An email address that can send and receive messages
• Thread — A conversation grouping related messages
• Message — An individual email (sent or received)
• Attachment — A file attached to a message (base64 encoded)

Inboxes

Create and manage email inboxes. Each inbox gets a unique email address.

Create Inbox

// Auto-generated address on default domain
const inbox = await client.inbox.create();

// Custom name and address
const inbox = await client.inbox.create({
  name: "notifications",
  email: "notifications@yourdomain.com",
});

curl -X POST https://api.sendook.com/v1/inboxes \
  -H "Authorization: Bearer $SENDOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "notifications", "email": "notifications@yourdomain.com"}'

Response 201 Created:

{
  "id": "inbox_abc123",
  "name": "notifications",
  "domainId": "dom_xyz789",
  "email": "notifications@yourdomain.com",
  "createdAt": "2025-01-15T10:30:00Z"
}

List Inboxes

const inboxes = await client.inbox.list();

curl https://api.sendook.com/v1/inboxes \
  -H "Authorization: Bearer $SENDOOK_API_KEY"

Get Inbox

const inbox = await client.inbox.get("inbox_abc123");

curl https://api.sendook.com/v1/inboxes/inbox_abc123 \
  -H "Authorization: Bearer $SENDOOK_API_KEY"

Delete Inbox

await client.inbox.delete("inbox_abc123");

curl -X DELETE https://api.sendook.com/v1/inboxes/inbox_abc123 \
  -H "Authorization: Bearer $SENDOOK_API_KEY"

Messages

Send, receive, and manage email messages.

Send Message

await client.inbox.message.send({
  inboxId: "inbox_abc123",
  to: ["recipient@example.com"],
  subject: "Hello from Sendook",
  text: "Plain text body",
  html: "<h1>Hello</h1><p>HTML body</p>",
});

curl -X POST https://api.sendook.com/v1/inboxes/inbox_abc123/messages/send \
  -H "Authorization: Bearer $SENDOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["recipient@example.com"],
    "subject": "Hello from Sendook",
    "text": "Plain text body",
    "html": "<h1>Hello</h1><p>HTML body</p>"
  }'

Response 202 Accepted — message queued for delivery.

Send with Attachments

import { readFileSync } from "fs";

await client.inbox.message.send({
  inboxId: "inbox_abc123",
  to: ["recipient@example.com"],
  subject: "Report attached",
  text: "Please find the report attached.",
  attachments: [
    {
      content: readFileSync("report.pdf").toString("base64"),
      name: "report.pdf",
      contentType: "application/pdf",
    },
  ],
});

Send with CC/BCC

await client.inbox.message.send({
  inboxId: "inbox_abc123",
  to: ["primary@example.com"],
  cc: ["cc@example.com"],
  bcc: ["bcc@example.com"],
  subject: "Team update",
  text: "Here's the latest update.",
});

Reply to Message

await client.inbox.message.reply({
  inboxId: "inbox_abc123",
  messageId: "msg_def456",
  text: "Thanks for your email!",
  html: "<p>Thanks for your email!</p>",
});

curl -X POST https://api.sendook.com/v1/inboxes/inbox_abc123/messages/msg_def456/reply \
  -H "Authorization: Bearer $SENDOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Thanks for your email!"}'

List Messages

// List all messages
const messages = await client.inbox.message.list("inbox_abc123");

// Search messages (regex-based)
const results = await client.inbox.message.list("inbox_abc123", "invoice");

# List all messages
curl https://api.sendook.com/v1/inboxes/inbox_abc123/messages \
  -H "Authorization: Bearer $SENDOOK_API_KEY"

# Search messages
curl "https://api.sendook.com/v1/inboxes/inbox_abc123/messages?query=invoice" \
  -H "Authorization: Bearer $SENDOOK_API_KEY"

Get Message

const message = await client.inbox.message.get("inbox_abc123", "msg_def456");

curl https://api.sendook.com/v1/inboxes/inbox_abc123/messages/msg_def456 \
  -H "Authorization: Bearer $SENDOOK_API_KEY"

Response:

{
  "id": "msg_def456",
  "from": "sender@example.com",
  "to": ["recipient@example.com"],
  "subject": "Hello",
  "text": "Plain text body",
  "html": "<p>HTML body</p>",
  "labels": [],
  "threadId": "thread_ghi789",
  "createdAt": "2025-01-15T10:35:00Z"
}

Threads

Threads group related messages into conversations.

List Threads

const threads = await client.inbox.thread.list("inbox_abc123");

curl https://api.sendook.com/v1/inboxes/inbox_abc123/threads \
  -H "Authorization: Bearer $SENDOOK_API_KEY"

Get Thread

const thread = await client.inbox.thread.get("inbox_abc123", "thread_ghi789");
// thread.messages contains all messages in the conversation

curl https://api.sendook.com/v1/inboxes/inbox_abc123/threads/thread_ghi789 \
  -H "Authorization: Bearer $SENDOOK_API_KEY"

Response:

{
  "id": "thread_ghi789",
  "subject": "Hello",
  "messages": [
    {
      "id": "msg_def456",
      "from": "sender@example.com",
      "to": ["recipient@example.com"],
      "subject": "Hello",
      "text": "Original message",
      "createdAt": "2025-01-15T10:35:00Z"
    },
    {
      "id": "msg_jkl012",
      "from": "recipient@example.com",
      "to": ["sender@example.com"],
      "subject": "Re: Hello",
      "text": "Reply message",
      "createdAt": "2025-01-15T10:40:00Z"
    }
  ]
}

Domain Management

Register and verify custom sending domains for branded email addresses.

Create Domain

const domain = await client.domain.create({ name: "yourdomain.com" });

curl -X POST https://api.sendook.com/v1/domains \
  -H "Authorization: Bearer $SENDOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "yourdomain.com"}'

Get DNS Records

After creating a domain, retrieve the required DNS records to configure.

const records = await client.domain.dns({ domainId: "dom_xyz789" });
// Returns MX, TXT (SPF/DKIM/DMARC), and CNAME records

curl https://api.sendook.com/v1/domains/dom_xyz789/dns \
  -H "Authorization: Bearer $SENDOOK_API_KEY"

Response:

[
  { "type": "MX", "name": "yourdomain.com", "value": "mx.sendook.com" },
  { "type": "TXT", "name": "yourdomain.com", "value": "v=spf1 include:sendook.com ~all" },
  { "type": "CNAME", "name": "sendook._domainkey.yourdomain.com", "value": "dkim.sendook.com" }
]

Verify Domain

After adding DNS records, verify the domain.

await client.domain.verify({ domainId: "dom_xyz789" });

curl -X POST https://api.sendook.com/v1/domains/dom_xyz789/verify \
  -H "Authorization: Bearer $SENDOOK_API_KEY"

Get Domain

const domain = await client.domain.get({ domainId: "dom_xyz789" });

Delete Domain

await client.domain.delete({ domainId: "dom_xyz789" });

Webhooks

Receive real-time notifications when email events occur. See references/webhooks.md for detailed payload documentation.

Create Webhook

const webhook = await client.webhook.create({
  url: "https://your-app.com/webhooks/email",
  events: ["message.received", "message.delivered", "message.bounced"],
});

curl -X POST https://api.sendook.com/v1/webhooks \
  -H "Authorization: Bearer $SENDOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/email",
    "events": ["message.received", "message.delivered", "message.bounced"]
  }'

Supported Events

List Webhooks

const webhooks = await client.webhook.list();

Get Webhook

const webhook = await client.webhook.get("wh_mno345");

Test Webhook

Send a test event to verify your endpoint is working.

await client.webhook.test("wh_mno345");

curl -X POST https://api.sendook.com/v1/webhooks/wh_mno345/test \
  -H "Authorization: Bearer $SENDOOK_API_KEY"

Delete Webhook

await client.webhook.delete("wh_mno345");

Express.js Webhook Handler

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/email", (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case "message.received":
      console.log(`New email from ${data.from}: ${data.subject}`);
      break;
    case "message.bounced":
      console.log(`Bounce for ${data.to}: ${data.subject}`);
      break;
    case "message.complained":
      console.log(`Spam complaint from ${data.to}`);
      break;
  }

  // Always return 200 immediately
  res.status(200).send("OK");
});

API Keys

Create and manage API keys for authentication.

Create API Key

const key = await client.apiKey.create({ name: "production" });

curl -X POST https://api.sendook.com/v1/api_keys \
  -H "Authorization: Bearer $SENDOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}'

List API Keys

const keys = await client.apiKey.list();

Get API Key

const key = await client.apiKey.get({ apiKeyId: "key_pqr678" });

Delete API Key

await client.apiKey.delete({ apiKeyId: "key_pqr678" });

Error Handling

try {
  await client.inbox.message.send({
    inboxId: "inbox_abc123",
    to: ["recipient@example.com"],
    subject: "Hello",
    text: "Body",
  });
} catch (error) {
  if (error.response) {
    // Server responded with error
    console.error(error.response.status, error.response.data);
  } else if (error.request) {
    // No response received
    console.error("No response:", error.request);
  } else {
    // Request setup failure
    console.error("Error:", error.message);
  }
}

Common Status Codes

Error response shape:

{
  "message": "Inbox not found",
  "code": "not_found",
  "details": {}
}

Best Practices

• Deliverability: Always configure SPF, DKIM, and DMARC records for custom domains. Use client.domain.dns() to get the required records, then verify with client.domain.verify().
• Webhooks: Return 200 immediately from webhook handlers and process events asynchronously. Use a message queue for heavy processing.
• Attachments: Base64 encoding increases file size by ~33%. Keep attachments under 10MB.
• Rate Limits: The API allows ~1,000 requests/minute and ~50,000 requests/day. Implement exponential backoff on 429 responses.
• Search: Use client.inbox.message.list(inboxId, query) with regex patterns to search across to/from/cc, subject, and body fields.
• Threading: Use client.inbox.thread.get() to retrieve full conversation history instead of fetching individual messages.

API Reference