mail

← All adapters

mail(folder: string, options: Partial<MailServerOptions>): Source<MailBody>
mail(folder: string): Destination<unknown, MailFetchResult>
mail(action: MailAction): Destination<unknown, void>
mail(options: MailServerOptions & { folder: string }): Destination<unknown, MailFetchResult>
mail(options?: Partial<MailClientOptions>): Destination<MailSendPayload, MailSendResult>

Read email via IMAP, send via SMTP, or perform IMAP operations. The adapter has four modes determined by the arguments you pass.

Source mode (IMAP push): Pass a folder and options to receive new messages via IMAP IDLE or polling. Each new email becomes a separate exchange.

The source follows the payload-on-body, envelope-on-headers convention shared with the HTTP source: the parsed message content (text, html, attachments) lands on exchange.body (a MailBody), and the envelope (from, to, subject, date, flags, sender, ...) lands on routecraft.mail.* headers. This means .input({ body }) validates against the message content alone, and the same .transform() / .filter() operators compose whether the payload arrived over mail or HTTP.

craft()
  .id('inbox-watcher')
  .from(mail('INBOX', { markSeen: true }))
  .to(log())

// Read the envelope off headers, the content off the body.
craft()
  .id('inbox-router')
  .from(mail('INBOX', { markSeen: true }))
  .filter((ex) => ex.headers['routecraft.mail.from']?.endsWith('@acme.test') ?? false)
  .transform((body) => body.text ?? '')
  .to(log())

Source delivery modes: the source runs in one of two modes.

• IDLE (default): the server pushes notifications when new mail arrives. The \Seen flag is the cross-cycle dedupe state, so each message is delivered exactly once per subscription. IDLE is the right default for "process each new email once" workloads.
• Poll (opt-in): set pollIntervalMs to fetch on a cadence instead of IDLE. Required whenever you opt out of the \Seen dedupe model (markSeen: false or unseen: false), for example to re-evaluate the inbox on every cycle and rely on a folder move as the done-signal. IDLE has no cycle boundary, so combining it with those overrides would refetch the entire folder on every inbound message; the source throws RC5003 at startup to prevent this footgun.

// Re-evaluate the inbox every minute; archive a message to mark it done.
// If you later extend `matchesCriteria`, previously-unmatched mail that is
// still in INBOX is picked up on the next cycle.
craft()
  .id('inbox-processor')
  .from(mail('INBOX', {
    pollIntervalMs: 60_000,
    markSeen: false,
    unseen: false,
  }))
  .filter(matchesCriteria)
  .process(processMessage)
  .to(mail({ action: 'move', folder: 'Archive' }))

The \Seen flag is written per-message after the handler resolves successfully, so a downstream failure leaves the message un-Seen and it is retried on the next cycle. limit combined with IDLE is a latency trap (backlog beyond the limit only drains when new mail arrives) and emits a warning at subscribe time.

Connection recovery: every connection-type failure on the source connection (the initial connect at route start, an IDLE drop, a failed fetch in either mode) goes through the same reconnect loop: exponential backoff with full jitter, growing from reconnect.baseDelayMs (default 1s) up to reconnect.maxDelayMs (default 60s), for up to reconnect.maxAttempts (default 30) consecutive failed attempts. After a reconnect the folder is drained immediately, so mail that arrived during the outage is delivered without waiting for the next new-arrival notification. Authentication failures never reconnect; they stop the route immediately with RC5012.

Because the initial connect retries too, the source signals readiness before the first connection succeeds: an IMAP server that is unreachable at route start leaves the route running in a degraded-but-recovering state, and route:started does not guarantee the mailbox was reachable. When the attempts cap is exhausted the source gives up with RC5010 and the route stops; subscribe to route:source:failed to alarm on a dead channel. Set reconnect: { maxAttempts: Infinity } for a channel that must never give up, or reconnect: false to disable recovery and fail on the first connection error.

// A long-lived agent channel: keep retrying forever, alarm via events.
craft()
  .id('inbox-agent')
  .from(mail('INBOX', { reconnect: { maxAttempts: Infinity } }))
  .to(processMessage())

Fetch destination (IMAP pull): Pass a folder string, or server options containing folder, to fetch messages. Use with .enrich() to pull mail on demand. The folder key is required in the object form: it is what distinguishes a fetch from a send, the same way http splits on path vs url.

craft()
  .id('check-inbox')
  .from(cron('0 */5 * * * *'))
  .enrich(mail('INBOX'))
  .to(log())

// Object form: `folder` is required and marks the fetch intent
craft()
  .id('check-unread')
  .from(cron('0 */5 * * * *'))
  .enrich(mail({ folder: 'INBOX', unseen: true, limit: 10 }))
  .to(log())

Send destination (SMTP): Call with no arguments or client options (no folder) to send email. The exchange body must be a MailSendPayload.

craft()
  .id('outbound')
  .from(direct())
  .to(mail())

Combined read and send:

// Forward unread mail to a different address. The incoming subject is on
// headers (envelope); the text content is on the body (payload).
craft()
  .id('mail-forwarder')
  .from(mail('INBOX', { unseen: true, markSeen: true }))
  .transform((body, ex) => ({
    to: 'team@example.com',
    subject: `Fwd: ${ex.headers['routecraft.mail.subject']}`,
    text: body.text ?? '',
  }))
  .to(mail())

IMAP operations: Call with a MailAction object to move, copy, delete, flag, unflag, or append messages.

// Archive after processing
craft()
  .id('archive-processed')
  .from(mail('INBOX', { unseen: true }))
  .tap(processMessage)
  .to(mail({ action: 'move', folder: 'Archive' }))

// Flag important messages
craft()
  .id('flag-important')
  .from(mail('INBOX', { subject: 'URGENT' }))
  .to(mail({ action: 'flag', flags: '\\Flagged' }))

Configuration via named accounts:

Mail connection details are set once in your craft.config.ts so individual routes do not need to repeat them. Each capability file re-exports the config:

// craft.config.ts
import type { CraftConfig } from '@routecraft/routecraft'

export const craftConfig: CraftConfig = {
  mail: {
    accounts: {
      default: {
        imap: {
          host: 'imap.gmail.com',
          auth: { user: process.env.MAIL_USER!, pass: process.env.MAIL_APP_PASSWORD! },
        },
        smtp: {
          host: 'smtp.gmail.com',
          auth: { user: process.env.MAIL_USER!, pass: process.env.MAIL_APP_PASSWORD! },
          from: process.env.MAIL_USER!,
        },
      },
    },
  },
}

// capabilities/inbox-watcher.ts
export { craftConfig } from '../craft.config'
import { craft, mail, log } from '@routecraft/routecraft'

export default craft()
  .id('inbox-watcher')
  .from(mail('INBOX', { markSeen: true }))
  .to(log())

When multiple accounts are configured, select one per adapter call with the account option:

.from(mail('INBOX', { account: 'support' }))
.to(mail({ account: 'notifications' }))

Server options (MailServerOptions):

Client options (MailClientOptions):

MailBody (source exchange body):

In source mode (.from(mail(...))) the exchange body is just the parsed message content. The envelope lives on headers.

Source headers (routecraft.mail.*):

In source mode the envelope is attached to exchange.headers under the routecraft.mail.* namespace. The keys are declaration-merged into RoutecraftHeaders (so you get autocomplete) and exported on the MailHeaders key object (MailHeaders.FROM, MailHeaders.SUBJECT, ...).

MailMessage (fetch destination result):

In fetch mode (.enrich(mail(...))) the result body is a MailMessage[]. Because a batch fetch returns many messages, each one keeps its whole envelope together in a single object rather than splitting across single-valued headers.

MailSender (on routecraft.mail.sender / MailMessage.sender):

Resolves the real sender of mailing-list and auto-forwarded messages, so apps can gate on origin without re-parsing headers. For a Google Groups forward, sender.address is the original sender and from is the rewritten list address.

Filter on the effective sender:

craft()
  .from(mail('INBOX'))
  .filter((ex) => {
    const s = ex.headers['routecraft.mail.sender'];
    if (s?.address === 'alice@allowed.com' && s.trust === 'verified') {
      return true;
    }
    return { reason: s?.reason ?? 'no sender info' };
  })
  .to(log())

MailSendPayload (exchange body for .to(mail())):

MailSendResult:

Exported types: MailAuth, MailServerOptions, MailClientOptions, MailOptions, MailBody, MailMessage, MailAttachment, MailSendPayload, MailSendResult, MailFetchResult, MailContextConfig, MailAccountConfig, MailAction, MailSender, EmailAddress, ForwardHop, ForwardType, TrustLevel, MailClientManager, MAIL_CLIENT_MANAGER. Header keys: the MailHeaders object (UID, FOLDER, MESSAGE_ID, FROM, TO, CC, BCC, SUBJECT, DATE, REPLY_TO, FLAGS, SENDER, RAW_HEADERS). Helpers: analyzeHeaders, parseAuthResults.