Session

The session object is created when a client connects and passed through every middleware phase. It is the primary way to share state across the connection lifecycle.

app.onConnect(async (ctx, next) => {
  console.log(ctx.session.remoteAddress); // e.g. "127.0.0.1"
  await next();
});

Fields

Field availability

Not every field is available in every phase:

• id, remoteAddress, clientHostname, openingCommand — available from onConnect onward
• secure — false initially; becomes true after STARTTLS or on SMTPS connections
• user — only available after ctx.accept(user) is called in onAuth
• envelope — fully populated after onRcptTo completes; partial during onMailFrom
• transmissionType — available from onMailFrom onward

Sharing state across phases

Since session is the same object throughout the connection, you can attach arbitrary data to session.user in onAuth and read it in later phases.

type AuthUser = { id: number; role: string };

app.onAuth(async (ctx, next) => {
  const user = await db.findByCredentials(
    ctx.credentials.username,
    ctx.credentials.password,
  );
  if (!user) {
    ctx.reject("Bad credentials", 535);
  }
  ctx.accept(user as AuthUser);
  await next();
});

app.onMailFrom(async (ctx, next) => {
  const user = ctx.session.user as AuthUser | undefined;
  if (user?.role !== "sender") {
    ctx.reject("Not authorized to send mail", 550);
  }
  await next();
});

The envelope

session.envelope contains the parsed MAIL FROM and RCPT TO data once those commands complete.

app.onData(async (ctx, next) => {
  const { mailFrom, rcptTo } = ctx.session.envelope;
  console.log("from:", mailFrom.address);
  console.log("to:", rcptTo.map((r) => r.address));
  await next();
});

Address fields

Each Address has two fields: