Mail Reference

The top-level mail facade exposes:

mail.inbox(options?)

mail.inbox(...) is a thin facade over the currently configured emails client. If no client has been configured, it throws a setup error that points callers to configureEmailsClient(...). Example:

import { mail } from "@qawolf/emails";

const inbox = await mail.inbox({ new: true });
console.log(inbox.emailAddress);

Inbox Handle

The returned inbox handle exposes:

emailAddress
sendMessage(...)
waitForMessage(...)
waitForMessages(...)

The current exported wait type is shared by both wait methods. The sections below describe which fields each method actually uses. Pass {} when you want default wait behavior. Example:

const inbox = await mail.inbox({ new: true });

await inbox.sendMessage({
  subject: "Sign in link",
  text: "Use the link in this email",
  to: [inbox.emailAddress],
});

const latestMessage = await inbox.waitForMessage({});

Current `GetInboxOptions`

type GetInboxOptions = {
  address?: string | undefined;
  delimiter?: string | undefined;
  new?: boolean | undefined;
};

Current validation and behavior:

new: true derives a unique address based on the current default
delimiter customizes the separator used for derived addresses
address must come from the allowed workspace address set
omitting address triggers a lookup of the workspace default address

If teamId is missing from the runtime client configuration, inbox creation fails. Examples:

const defaultInbox = await mail.inbox();
const namedInbox = await mail.inbox({ address: "flows@example.com" });
const derivedInbox = await mail.inbox({ new: true, delimiter: "-" });

`sendMessage(...)`

Current input shape:

type SendMessage = {
  attachments?: {
    content: Buffer;
    contentId?: string;
    disposition?: "attachment" | "inline";
    fileName: string;
    type?: string;
  }[];
  bcc?: string[];
  cc?: string[];
  html?: string;
  replyTo?: string[];
  replyToMessageId?: string;
  subject: string;
  text?: string;
  to: string[];
};

Behavior:

to is always an array of strings
at least one of html or text is required
attachments are base64-encoded before the request is sent to the email service

Return shape:

type SendMessageResult = {
  id: string;
};

Example:

const result = await inbox.sendMessage({
  attachments: [
    {
      content: Buffer.from("hello"),
      fileName: "note.txt",
      type: "text/plain",
    },
  ],
  html: "<p>Hello from QA Wolf</p>",
  subject: "Welcome",
  to: [inbox.emailAddress],
});

console.log(result.id);

`waitForMessage(...)`

Current method options:

type WaitForMessageOptions = {
  after?: Date;
  timeout?: number;
};

For waitForMessage(...), the implementation uses:

after when it is provided
otherwise the time when mail.inbox(...) was called
timeout when it is provided

It returns one ParsedEmail and throws if no message arrives in time. Example:

const message = await inbox.waitForMessage({
  after: new Date(Date.now() - 60_000),
  timeout: 15_000,
});

console.log(message.subject);

`waitForMessages(...)`

Current method options:

type WaitForMessagesOptions = {
  after?: Date;
  delay?: number;
  minCount?: number;
  timeout?: number;
};

Behavior:

it uses after when provided, otherwise the time when mail.inbox(...) was called
it waits for delay first
it polls until at least minCount messages are found, or until timeout
it returns the matching parsed emails

Example:

const messages = await inbox.waitForMessages({
  delay: 2_000,
  minCount: 2,
  timeout: 30_000,
});

console.log(messages.map((message) => message.subject));

Parsed Email Shape

The parsed email shape is:

type ParsedEmail = {
  attachments?: {
    content: Buffer;
    fileName: string;
    type?: string;
  }[];
  bcc?: string[];
  cc?: string[];
  from: string;
  html: string;
  id: string;
  replyTo?: string[];
  subject: string;
  teamId: string;
  text: string;
  to: string[];
  urls: string[];
};

urls is derived by parsing links from the HTML body. Example:

const message = await inbox.waitForMessage({});

console.log(message.from);
console.log(message.subject);
console.log(message.urls);

@qawolf/flows

@qawolf/pom

@qawolf/testkit

@qawolf/emails

@qawolf/ci-sdk

@qawolf/cli

REST

Inbox Handle

Current `GetInboxOptions`

`sendMessage(...)`

`waitForMessage(...)`

`waitForMessages(...)`

Parsed Email Shape

​Inbox Handle

​Current GetInboxOptions

​sendMessage(...)

​waitForMessage(...)

​waitForMessages(...)

​Parsed Email Shape

Inbox Handle

Current `GetInboxOptions`

`sendMessage(...)`

`waitForMessage(...)`

`waitForMessages(...)`

Parsed Email Shape