Developer Documentation

import { OonruMail } from "@oonrumail/sdk";

const mail = new OonruMail({
  apiKey: "em_live_...",             // Required — your API key
  baseUrl: "https://api.oonrumail.com",  // Default
  timeout: 30000,                    // Request timeout (ms)
  maxRetries: 3,                     // Retries on 5xx / 429
});

import { OonruMail } from "@oonrumail/sdk";

const mail = new OonruMail({
  apiKey: process.env.OONRUMAIL_API_KEY,
});

const result = await mail.send({
  from: "noreply@myapp.com",
  to: ["user@example.com"],
  subject: "Welcome!",
  html: "<h1>Welcome aboard</h1>",
});

console.log(result.message_id);  // "msg-abc123"

await mail.sendSimple({
  from: "noreply@myapp.com",
  to: "user@example.com",     // single string or array
  subject: "Hello",
  html: "<p>Hello world</p>",
});

await mail.send({
  from: "noreply@myapp.com",
  to: ["user@example.com"],
  cc: ["cc@example.com"],
  bcc: ["bcc@example.com"],
  reply_to: "support@myapp.com",
  subject: "Order Confirmed",
  html: "<h1>Order #123</h1>",
  text: "Order #123 confirmed",      // plain text fallback
  categories: ["orders"],
  custom_args: { order_id: "123" },
  track_opens: true,
  track_clicks: true,
  attachments: [
    {
      filename: "invoice.pdf",
      content: btoa("..."),           // base64 encoded
      content_type: "application/pdf",
    },
  ],
});

await mail.sendWithTemplate({
  from: "noreply@myapp.com",
  to: "user@example.com",
  template_id: "tpl-welcome-v2",
  substitutions: {
    name: "Alice",
    company: "Acme",
  },
});

const result = await mail.sendBatch({
  messages: [
    { from: "noreply@app.com", to: ["a@b.com"], subject: "Hi A", html: "..." },
    { from: "noreply@app.com", to: ["c@d.com"], subject: "Hi C", html: "..." },
  ],
});

console.log(`Queued: ${result.total_queued}`);

await mail.send({
  from: "noreply@app.com",
  to: ["user@example.com"],
  subject: "Reminder",
  html: "<p>Don't forget!</p>",
  send_at: "2026-03-01T09:00:00Z",
});

const tpl = await mail.templates.create({
  name: "Welcome Email",
  subject: "Welcome {{name}}!",
  html_content: "<h1>Hi {{name}}</h1><p>Welcome to {{company}}.</p>",
  variables: [
    { name: "name", type: "string", required: true },
    { name: "company", type: "string", default_value: "OonruMail" },
  ],
  category: "onboarding",
  tags: ["welcome", "new-user"],
});

// List all templates in a category
const { templates } = await mail.templates.list({
  category: "onboarding",
});

// Clone an existing template
const copy = await mail.templates.clone(tpl.id, {
  name: "Welcome v2",
});

const rendered = await mail.templates.render(tpl.id, {
  name: "Alice",
});

console.log(rendered.html);     // "<h1>Hi Alice</h1>..."
console.log(rendered.subject);  // "Welcome Alice!"

// Update
await mail.templates.update(tpl.id, {
  subject: "Hey {{name}}!",
});

// Delete
await mail.templates.delete(tpl.id);

const wh = await mail.webhooks.create({
  url: "https://myapp.com/hooks/email",
  events: ["delivered", "bounced", "opened", "clicked"],
  description: "Production webhook",
});

console.log(wh.secret);  // Save this!

import { OonruMail } from "@oonrumail/sdk";

// In your Express / Next.js / Fastify handler:
const isValid = await OonruMail.verifyWebhookSignature(
  rawBody,
  request.headers["x-webhook-signature"],
  process.env.WEBHOOK_SECRET
);

if (!isValid) {
  return new Response("Invalid signature", { status: 401 });
}

const payload = OonruMail.parseWebhookPayload(rawBody);

switch (payload.event) {
  case "delivered":
    console.log(`Delivered to ${payload.recipient}`);
    break;
  case "bounced":
    console.log(`Bounced: ${payload.bounce_type} — ${payload.reason}`);
    break;
}

// Test endpoint
const test = await mail.webhooks.test(wh.id, "delivered");
console.log(test.success, test.latency_ms);

// Rotate signing secret
const { secret } = await mail.webhooks.rotateSecret(wh.id);

// View recent deliveries (filter for failures)
const { deliveries } = await mail.webhooks.listDeliveries(wh.id, {
  limit: 10,
  success: false,
});

const check = await mail.suppressions.check(["user@example.com"]);

if (check.results["user@example.com"].suppressed) {
  console.log("Email is suppressed — skipping");
}

// Add a single address
await mail.suppressions.create({
  email: "bad@example.com",
  reason: "manual",
  description: "User requested removal",
});

// Bulk add (up to 1,000)
const result = await mail.suppressions.bulkCreate({
  emails: ["a@bad.com", "b@bad.com"],
  reason: "invalid",
});

console.log(`Added: ${result.added}`);
console.log(`Already existed: ${result.existing}`);

const stats = await mail.suppressions.stats();
console.log(`Total suppressed: ${stats.total}`);

const { messages } = await mail.messages.list({
  status: "delivered",
  limit: 20,
});

const timeline = await mail.messages.timeline(messageId);

for (const event of timeline.events) {
  console.log(`${event.event_type} at ${event.timestamp}`);
}

const events = await mail.events.list({
  event_type: "bounced",
  limit: 50,
});

const stats = await mail.analytics.overview({
  start_date: "2026-01-01",
  end_date: "2026-01-31",
});

console.log(`Delivery rate: ${stats.delivery_rate}%`);
console.log(`Open rate: ${stats.open_rate}%`);
console.log(`Total sent: ${stats.total_sent}`);

const ts = await mail.analytics.timeseries({
  interval: "day",   // "hour" | "day" | "week" | "month"
});

for (const point of ts.data) {
  console.log(`${point.date}: ${point.sent} sent, ${point.delivered} delivered`);
}

const bounces = await mail.analytics.bounces();

console.log(`Hard bounces: ${bounces.hard}`);
console.log(`Soft bounces: ${bounces.soft}`);
console.log(`Top reasons:`, bounces.top_reasons);

const rt = await mail.analytics.realtime();

console.log(`${rt.sent_last_minute} emails/min`);
console.log(`${rt.active_connections} active connections`);

const rep = await mail.analytics.reputation();

console.log(`Reputation score: ${rep.score}`);
console.log(`Status: ${rep.status}`);  // "good" | "warning" | "critical"

const { key, api_key } = await mail.apiKeys.create({
  domain_id: "domain-uuid",
  name: "Platform X Production",
  scopes: ["send", "read", "templates"],
  rate_limit: 500,     // requests per minute
  daily_limit: 10000,  // emails per day
});

console.log(`Key: ${key}`);  // Only shown once!

// Check usage over last 7 days
const usage = await mail.apiKeys.usage(api_key.id, 7);

// Rotate (revoke old key, create new one)
const rotated = await mail.apiKeys.rotate(api_key.id);
console.log(`New key: ${rotated.key}`);

// Revoke permanently
await mail.apiKeys.revoke(api_key.id);