Mail apps, SMTP and forwarding

SMTP submission#

SMTP is an alternative to POST /v1/emails. A message goes through the same pipeline: the sender must be on a verified domain of the key's workspace, and plan limits, suppressions, DKIM, message.* events, webhooks and the Sending log all apply. See Sending.

import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "smtp.runearc.com",
  port: 465,
  secure: true, // port 587 with secure: false and requireTLS: true also works
  auth: { user: "runearc", pass: process.env.RUNEARC_API_KEY },
});

await transport.sendMail({ from: "Acme <noreply@acme.com>", to: "user@example.com", subject: "Welcome", text: "Hello" });

250 2.0.0 OK queued as eml_... is returned only after the email is stored and handed to the mail transport; temporary failures are 451 4.3.0 so clients retry. A message whose Message-ID was already accepted in the workspace is not sent again; the server answers 250 with the original email id. A sender outside your verified domains gets 550 5.7.1 with a fix. Bcc headers are removed. To use a template over SMTP, see the headers on Emails API.

App passwords#

Mail apps use an app password for one inbox instead of an API key. It acts as the user who made it, limited to that inbox and capped at the Support role: it reads, and sends or replies only if the user's role may reply (a Viewer's reads only). It stops working as soon as the user is removed from the workspace or loses the inbox.

Dashes and case in the password do not matter. At most 20 per user per inbox (app_password_limit_reached). Creating and revoking are in the audit log. App passwords are made from a dashboard session; there is no CLI command or MCP tool.

IMAP#

Runearc serves an IMAP4rev1 subset with IDLE, MOVE, UIDPLUS, UNSELECT, NAMESPACE, ID, ENABLE, SPECIAL-USE, LITERAL+ and SASL-IR, so new mail shows within seconds. Mail the inbox sends over SMTP with the same app password appears in Sent, and a reply continues its conversation.

Conversations, not single messages, are open or closed. \Seen is the dashboard's read state for the user. Deleting and expunging hide a message from that app password only; nothing is deleted for the team. There is no Drafts mailbox: apps keep drafts locally. UIDs are stable and UIDVALIDITY never changes.

Limits: 60 new connections per client IP a minute, 10 failed sign ins per IP and per username in 10 minutes (then NO [UNAVAILABLE]), 60 seconds to sign in and 30 minutes idle before logout. Typical errors: NO [AUTHENTICATIONFAILED] (wrong or revoked password, make a new one), NO [PRIVACYREQUIRED] (use TLS or STARTTLS) and NO [NOPERM] when archiving (the role cannot reply in the inbox).

Forwarding#

An inbox can forward a copy of every message it receives to other addresses. Adding a target emails it a confirmation link; it stays pending until the link is opened (valid 7 days), then active. Each inbox has at most 10 targets.

The copy is sent from "Original Name via Runearc" <forwarding@<inbox domain>> with Reply-To set to the inbox, so a reply lands back in the inbox and threads. The original headers are kept as X-Original-*, and copies carry X-Runearc-Forwarded: 1 so mail is never forwarded twice. Each copy counts as one sent email against the plan, and suppressed targets are skipped. Forwarding has no CLI command or MCP tool.

Errors#