> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qawolf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mail Reference

> Reference for the @qawolf/emails mail API, covering inbox creation, sending messages, and waiting for parsed emails inside flows.

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:

```ts theme={null}
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:

```ts theme={null}
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`

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
type SendMessageResult = {
  id: string;
};
```

Example:

```ts theme={null}
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:

```ts theme={null}
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:

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

console.log(message.subject);
```

## `waitForMessages(...)`

Current method options:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
const message = await inbox.waitForMessage({});

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