Send and reply

Ways to send

Use the web composer for human conversations. Use the REST API, TypeScript SDK, or MCP for product and agent workflows. Every path performs the same mailbox permission, policy, suppression, size, and usage checks.

Start a conversation

A new message needs a mailbox, one to ten to recipients, a subject, and plain text. HTML, CC, BCC, and uploaded attachment IDs are optional.

const sent = await mail.sendEmail({
  mailboxId: "mbx_123",
  to: ["customer@example.com"],
  subject: "Your export is ready",
  text: "Download it from your account for the next 24 hours.",
});

The send endpoint returns 202 Accepted because delivery continues asynchronously. Save the returned messageId and threadId when your workflow needs to reconcile later.

Reply in a thread

Pass the ID of an existing message as replyToMessageId. Startup Mail creates the correct reply headers and associates the outgoing message with the conversation.

await mail.reply({
  mailboxId: "mbx_123",
  replyToMessageId: "msg_456",
  to: ["customer@example.com"],
  subject: "Re: Your export is ready",
  text: "Happy to help—I've regenerated the link.",
});

Sending rules

Allowed mail is a direct conversation or a transactional message the recipient requested or reasonably expects. Newsletters, promotional campaigns, drip sequences, cold outreach, purchased lists, and scraped contacts are prohibited.

Read the full acceptable use policy.