Mailbox API

​

Before you start

• Create the mailbox in Ozi first, under Mailboxes. The API reads and sends mail for mailboxes that already exist; it does not create them.
• Use an API key with Full access. Keys set to Sending only - the kind you hand to an app that just sends notifications - get 403 FORBIDDEN from every mailbox endpoint, because these endpoints read people’s mail.
• A key restricted to one domain only sees that domain’s mailboxes. Conversations, messages and attachments outside the key’s team or domain return 404, exactly as if they did not exist.

​

Endpoints

​

Using the SDK

import { Ozi } from "ozi-js";

const ozi = new Ozi(process.env.OZI_API_KEY);

// Every mailbox the key can reach
const { data: mailboxes } = await ozi.mailboxes.list();

// The newest conversations in one mailbox's inbox, page by page
let cursor: string | undefined;
do {
  const { data, error } = await ozi.threads.list({
    mailbox: mailboxes!.data[0]!.id,
    folder: "inbox",
    cursor,
    limit: 20,
  });
  if (error) throw new Error(error.message);

  for (const thread of data!.data) {
    console.log(thread.subject, thread.unread);
  }
  cursor = data!.next_cursor ?? undefined;
} while (cursor);

// One conversation with its messages, oldest first
const { data: thread } = await ozi.threads.get("cm9abc123");

// Reply to whoever wrote last. The key makes a retry safe.
await ozi.threads.reply(
  "cm9abc123",
  { text: "Thanks - we're on it." },
  { idempotencyKey: "ticket-4521-reply-1" },
);

// Mark it read and archive it
await ozi.threads.update("cm9abc123", { read: true, folder: "archive" });

// Save an attachment
const message = thread!.messages[0]!;
const attachment = message.attachments[0]!;
const { data: file } = await ozi.attachments.download(message.id, attachment.id);
// In Node: fs.writeFileSync(file!.filename ?? "attachment", Buffer.from(file!.content));

​

How it behaves

• Reading does not change anything. Getting a thread never marks it read. Mark it read yourself with PATCH /v1/threads/{id}.
• Paging is stable. Threads come newest first. Pass next_cursor back as cursor; new mail arriving while you page lands on the first page and never shifts the pages after it.
• Drafts are left out unless you ask for folder=drafts, and messages a mail app has marked for deletion never appear.
• Long bodies are cut, not refused. A message’s text and html are trimmed in API responses when they are very large. A thread returns its latest 100 messages.
• Replies go to the person who wrote last, and are filed in the mailbox’s Sent folder like a reply from webmail. They can be plain text or formatted (see below).
• New messages start their own thread. POST /v1/mailboxes/{id}/messages sends to up to three addresses, gets the mailbox signature, is filed in Sent and returns the new thread_id. It never joins an existing conversation, even one with the same subject. A recipient on your suppression list refuses the whole message (recipient_suppressed) rather than sending to the others.
• Attachments download as files. They always come back with Content-Disposition: attachment. Images embedded in a message body are not listed and cannot be downloaded through the API, and attachments over 25 MB were never stored, so they return 404 with a message saying so.

​

Formatted messages, pictures and scheduling

• html is a formatted body, up to 2 MB. It is cleaned on the server with the same rules webmail uses for what people write: scripts, forms, event handlers, <style> blocks, frames and unsafe links are removed before it is sent, so send ordinary formatting (paragraphs, bold, lists, links, tables, inline styles, pictures). When you leave out text, the plain-text copy is made from the HTML. The mailbox signature is added on the server: above an element with class="ozi_quote" when the body has one (wrap the quoted message you reply to in it), otherwise at the end. Do not add it yourself.
• inline_images are pictures shown in the HTML, up to 10, each { "cid", "filename", "content_type", "content_base64" }. Show one with <img src="cid:logo">. cid is 1-64 letters, digits, ., _ or -, and unique in the message. content_type is image/png, image/jpeg, image/gif or image/webp, and the bytes must really be that type: they are checked. Each picture can be up to 1,350,000 bytes (the largest picture webmail’s composer holds). Every cid: the HTML shows must be supplied, and every picture supplied must be shown; otherwise the request is refused with 400 and nothing is sent. The filename’s extension is corrected to match the type.
• draft_id names a draft of the same mailbox that this message replaces, such as the one a cancelled send became. Once the message is sent (or scheduled) the draft is deleted, as webmail does. It must be in that mailbox’s Drafts folder; anything else returns 404 and nothing is sent.
• send_at (RFC 3339, such as 2026-10-09T09:00:00Z) holds the message until then, up to a year ahead. It waits in the mailbox’s Scheduled folder, where webmail shows it too, and the response has "scheduled": true, the scheduled_id and the send_at. A mailbox can have up to 100 messages waiting.

const logo = fs.readFileSync("logo.png").toString("base64");

await fetch(`https://app.getozi.com/api/v1/mailboxes/${mailboxId}/messages`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OZI_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "invoice-4521",
  },
  body: JSON.stringify({
    to: ["[email protected]"],
    subject: "Your invoice",
    html: '<p>Hi Ada,</p><p>Your <b>March</b> invoice is ready.</p><img src="cid:logo">',
    inline_images: [
      { cid: "logo", filename: "logo.png", content_type: "image/png", content_base64: logo },
    ],
    send_at: "2026-10-09T09:00:00Z",
  }),
});

​

Undo send

​

Changing a waiting message

​

Saved replies

​

Getting told about new mail

{
  messageId: string;          // The message
  mailboxId: string;          // The mailbox it belongs to
  mailboxAddress: string;     // e.g. "[email protected]"
  threadId: string;           // The conversation - fetch it with GET /v1/threads/{id}
  folder: string;             // "INBOX", "SENT", "SPAM", ... or "CUSTOM"
  direction: "INBOUND" | "OUTBOUND";
  from: string;
  to: string[];
  cc: string[];
  subject: string;
  snippet: string | null;     // The start of the message text
  hasAttachments: boolean;
  sizeBytes: number;
  spamVerdict: string | null; // The spam check's result, for received mail
  receivedAt: string;         // ISO 8601 timestamp
}

​

Errors