@sendmux/mailbox

Generated TypeScript client for the Sendmux Mailbox API.

Documentation

• Mailbox API reference: sendmux.ai/docs/mailbox-api/introduction
• Source repository: Sendmux/sendmux-sdk

Requirements

• A mailbox-scoped smx_mbx_* key or scoped smx_agent_* token; alternatively, a REST OAuth grant for this surface.
• A JavaScript runtime with the standard Fetch API.

Installation

npm install @sendmux/mailbox

Migrate from 1.x to 2.0

If you construct thread-message list results — fixtures, mocks, or wrappers annotated with the operation's result type — add the thread identity before upgrading to 2.0. mailboxListThreadMessages returns MailboxThreadMessageSummaryCursorListResponse instead of MailboxMessageSummaryCursorListResponse: its meta.thread_id is required and meta.sync_state is an optional string. Code that only reads thread-message results keeps compiling.

1. Derive the result type from the public operation. The package doesn't export the generated model names directly:

   import { mailboxListThreadMessages } from "@sendmux/mailbox";
   
   type ThreadMessageList = NonNullable<
     Awaited<ReturnType<typeof mailboxListThreadMessages>>["data"]
   >;

2. Add the thread identity to every constructed thread-message result:

   // Before: meta: { request_id: "req_fixture" }
   const fixture: ThreadMessageList = {
     ok: true,
     meta: { request_id: "req_fixture", thread_id: "thr_1" },
     data: [],
     pagination: { has_more: false },
   };

   Ordinary mailboxListMessages results remain MailboxMessageSummaryCursorListResponse: they have no thread identity and expose an optional typed meta.sync_state. Identity, submission, quota, and thread list responses likewise expose optional typed state metadata (identity_state, query_state); no new field is required there.

3. Run your application's TypeScript check. A constructed thread-message result without meta.thread_id fails with Property 'thread_id' is missing in type … but required in type 'MailboxThreadMessagesMeta'.

Update @sendmux/mailbox, its lockfile, and affected result annotations or fixtures together. To roll back, restore those package, lockfile, and call-site changes together.

OAuth access tokens

Pass accessToken instead of apiKey for a REST OAuth token or synchronous/asynchronous provider.

import { createMailboxClient } from "@sendmux/mailbox";

const client = createMailboxClient({
  accessToken: () => process.env.SENDMUX_ACCESS_TOKEN!,
});

The provider runs before each request. Your application owns token storage and refresh; required scopes still apply. See OAuth setup.

Usage

import {
  createMailboxClient,
  mailboxListMessages,
  streamMailboxEvents,
} from "@sendmux/mailbox";

const client = createMailboxClient({
  apiKey: process.env.SENDMUX_MAILBOX_API_KEY!,
});

const messages = await mailboxListMessages({
  client,
  query: { limit: 50 },
});

console.log(messages.data);

The package exports every generated Mailbox operation plus:

• createMailboxClient
• configureMailbox
• MailboxClient
• streamMailboxEvents
• Node-only helpers from @sendmux/mailbox/node: downloadMailboxAttachmentToBuffer, readMailboxTextAttachment, uploadMailboxAttachmentFromFile, createMailboxAttachmentUploadFromFile, uploadMailboxAttachmentViaPresignedFile, and sendMailboxMessageWithFiles

Attachments

Message and event attachment metadata includes download_url, a short-lived presigned URL for that single attachment. In Node, prefer downloadMailboxAttachmentToBuffer or readMailboxTextAttachment from @sendmux/mailbox/node when you already have an authenticated client. Plain HTTP clients can fetch download_url promptly with no Authorization header; if it expires, call mailboxGetMessage or list/search messages again to receive fresh metadata.

Mailbox direct uploads, presigned uploads, and Node file helpers share the mailbox attachment cap, currently 7,500,000 bytes per attachment. Presigned uploads also pin the exact declared byte length and content type.

import {
  createMailboxClient,
  mailboxGetMessage,
  mailboxSendMessage,
  mailboxUploadAttachment,
} from "@sendmux/mailbox";

const client = createMailboxClient({
  apiKey: process.env.SENDMUX_MAILBOX_API_KEY!,
});

const message = await mailboxGetMessage({
  client,
  path: { message_id: "msg_123" },
  throwOnError: true,
});
const attachment = message.data.data.attachments?.[0];
if (attachment?.download_url) {
  const downloaded = await fetch(attachment.download_url);
  const bytes = await downloaded.arrayBuffer();
}

const upload = await mailboxUploadAttachment({
  client,
  body: new Blob(["hello\n"], { type: "text/plain" }),
  query: { filename: "hello.txt" },
  headers: { "Content-Type": "text/plain" },
  throwOnError: true,
});

await mailboxSendMessage({
  client,
  body: {
    to: [{ email: "[email protected]", name: null }],
    subject: "Attachment",
    text_body: "See attached.",
    attachments: [{
      blob_id: upload.data.data.blob_id,
      filename: "hello.txt",
      content_type: "text/plain",
    }],
  },
});

For local files in Node, use the helper subpath so file bytes stay out of model context and browser bundles:

import { createMailboxClient } from "@sendmux/mailbox";
import { readMailboxTextAttachment, sendMailboxMessageWithFiles } from "@sendmux/mailbox/node";

const client = createMailboxClient({ apiKey: process.env.SENDMUX_MAILBOX_API_KEY! });

await sendMailboxMessageWithFiles({
  client,
  files: ["./report.pdf"],
  headers: { "Idempotency-Key": "report-123" },
  body: {
    to: [{ email: "[email protected]", name: null }],
    subject: "Report",
    text_body: "Attached.",
  },
});

const text = await readMailboxTextAttachment({
  client,
  messageId: "msg_123",
  attachmentId: "att_123",
});

Use uploadMailboxAttachmentViaPresignedFile(...) when you want the upload step to use the short-lived signed URL and no API key on the file PUT. Inline base64 attachments remain available for tiny generated sends through the generated attachments[].content body shape.

Events

Use streamMailboxEvents for server-sent mailbox events.

for await (const event of streamMailboxEvents({
  client,
  query: { close_after: 300, event_types: "message.received" },
})) {
  console.log(event.event_type, event.message_id);
}

Pagination

Use paginate from @sendmux/core with list operations that return cursor pagination.

import { paginate } from "@sendmux/core";
import {
  createMailboxClient,
  mailboxListMessages,
} from "@sendmux/mailbox";

const client = createMailboxClient({
  apiKey: process.env.SENDMUX_MAILBOX_API_KEY!,
});

for await (const message of paginate(async (cursor) => {
  const response = await mailboxListMessages({
    client,
    query: { cursor, limit: 50 },
    throwOnError: true,
  });
  return response.data;
})) {
  console.log(message.id);
}

Support

Open an issue in Sendmux/sendmux-sdk with the package name, version, and request ID from any API error.

Licence

MIT. See the licence file.