Compose and send

Send new messages, reply or forward in context, and save drafts while tracking approvals and delivery waits.

Start with an existing mailbox and a client allowed to send from it. A mailbox-scoped key needs send; saving or editing drafts also needs update. A new message leaves from the mailbox's default email endpoint, with that endpoint's sender name. Agents and keys explains how to limit access and require approval.

Send a new message

Supply recipients, a subject, and at least one of text or html. The SDK generates an idempotency key for each call and preserves it across built-in retries. Pass an explicit key in the second argument when a job might repeat the same request across separate calls.

send-message.ts
import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });
const id = "mbx_...";

const receipt = await samva.mailboxes.sendMessage(
  {
    id,
    to: ["customer@example.com"],
    subject: "Your support request",
    text: "We are looking into your request.",
  },
  { idempotencyKey: "support-request-123-first-response" },
);
console.log(receipt.state, receipt.actionId, receipt.problem);

Optional cc, bcc, and replyTo address lists let you include other recipients or choose where answers return. See send a message for the request.

Reply or forward in context

Use a message ID from reading the conversation. reply addresses the message's Reply-To, or its sender when Reply-To is absent, and sets the subject and threading headers, and it leaves from the endpoint the thread belongs to, even when another endpoint is the default. replyAll also includes the other recipients and excludes the mailbox's own addresses.

reply-and-forward.ts
import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

const id = "mbx_7q2xk9mvt4znw8rh";

const messageId = "msg_...";

await samva.mailboxes.reply(
  {
    id,
    messageId,
    text: "Thanks, we have the details we need.",
  },
  { idempotencyKey: "support-request-123-reply" },
);

await samva.mailboxes.forward(
  {
    id,
    messageId,
    to: ["specialist@example.com"],
    text: "Could you help with this request?",
  },
  { idempotencyKey: "support-request-123-forward" },
);

Forwarding quotes the chosen message and copies its attachments into attachments owned by your organization; any attachments you supply are added to them. The combined attachments must fit the email attachment limits. See reply, reply all, and forward for the precise inputs.

Save a draft before sending

Drafts belong to their author. Listing drafts returns summaries without bodies; getDraft reads the full draft. A new-message draft can be incomplete while you work.

save-and-send-draft.ts
import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

const id = "mbx_7q2xk9mvt4znw8rh";

const draft = await samva.mailboxes.createDraft({
  id,
  to: ["customer@example.com"],
  subject: "Your support request",
  text: "We are checking the details.",
});

await samva.mailboxes.updateDraft({
  id,
  draftId: draft.id,
  text: "The details are confirmed. Your request is complete.",
});

const draftReceipt = await samva.mailboxes.sendDraft(
  {
    id,
    draftId: draft.id,
  },
  { idempotencyKey: "support-request-123-final-response" },
);
console.log(draftReceipt.state, draftReceipt.actionId);

To save a reply draft, pass inReplyToMessageId to createDraft; it must name a message in that mailbox. The reply stays in its conversation. A draft without a reply target sends as a new conversation. Sending requires recipients, a subject, and a body, including for reply drafts.

To save a forward as a draft, leave inReplyToMessageId out, quote the original in html, and pass each original attachment through copy a message attachment, which returns an attachment your draft can carry in attachments. The draft sends as a new conversation.

Each field in updateDraft replaces that field; omitted fields stay. null clears an optional field, and an empty to list removes recipients. See create a draft and update a draft.

A saved draft is editable and deletable. Sending locks the draft with state locked and lockedByActionId identifying the action. Its content stays unchanged while approval, sending, or reconciliation is pending; it cannot be edited, deleted, or sent again. An authorized reviewer can read the held draft. Denial, cancellation, or a definite unsent outcome returns it to its author as an editable draft. Changing and sending it creates a new action and requires any applicable approval. Acceptance marks it sent; it cannot be edited or resent. Follow Approve sends for the review workflow.

Attach a file

Send and draft requests accept attachments. Each attachment has a filename, contentType, size, and exactly one source: base64 content or the mediaId of a ready upload belonging to your organization. A mailbox-only key can complete or attach only uploads created with that same key. An upload created with a setup key or another agent's key returns 404; create a new upload with the sending key instead. Declared size and content type must match the uploaded file. A message's attachment ID or download URL is not an outbound media ID.

attach-file.ts
import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

const id = "mbx_7q2xk9mvt4znw8rh";

await samva.mailboxes.sendMessage(
  {
    id,
    to: ["customer@example.com"],
    subject: "Your receipt",
    text: "Your receipt is attached.",
    attachments: [
      { filename: "receipt.txt", content: "SGVsbG8=", contentType: "text/plain", size: 5 },
    ],
  },
  { idempotencyKey: "support-request-123-receipt" },
);

For larger files, upload and complete organization-owned media before attaching its ID. The email attachments guide owns size limits and upload instructions.

Send receipts

New messages, replies, forwards, and draft sends record an action and return its receipt. A 202 response means the action is held, queued, or needs reconciliation; it does not confirm sending. Read state, save actionId, and follow the same action through mailboxes.getAction.

messageId and acceptedAt become available once Samva establishes acceptance. Acceptance does not confirm arrival in the recipient's inbox. waitReason describes a reported delivery wait, and reviewExpectedAt is an estimate for a content review decision rather than a promised delivery time. See email delivery for delivery outcomes.

skippedRecipients lists excluded addresses with their reasons. Check it even after acceptance, because acceptance does not mean every requested address is included. The send response reference defines the complete shape. Read a send receipt explains each action state, problem, and sending deadline.

Retry without creating another send

After a lost response, repeat the same operation with the same body and Idempotency-Key to observe the original action. Reusing a key with a different body returns 409. Once you know actionId, read that action to establish the outcome rather than submitting another send.

A queued action can wait automatically within its fixed sending deadline. A permitted person can Cancel or retry when the action allows it; retry never extends that deadline. An uncertain outcome needs reconciliation, not a replacement request key. Recover a lost response defines key retention and explains when reusing an old key can create another intentional send.

Find your drafts across mailboxes

In Samva Mail, choose All mailboxes → Drafts to resume your own drafts. Each row shows its mailbox address; opening it uses that mailbox as the sending identity. Drafts stay private to their author, including in shared mailboxes. Administrators cannot read another person's personal drafts.

The API's GET /v1/mailboxes/drafts returns a cursor-paged summary list with each draft's mailbox { id, address, kind }. Repeat mailboxId to narrow the list, or pass kind or threadId. Only mailboxes where the caller may write drafts are included. Read the body using the row's mailbox ID with GET /v1/mailboxes/{id}/drafts/{draftId}.

list-your-drafts.ts
import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });
const page = await samva.mailboxes.listOrganizationDrafts({ kind: "shared", limit: 20 });
for (const draft of page.items) {
  console.log(draft.subject, draft.mailbox.address);
}

Related documentation

On this page