### Start example server with real SMTP

Source: https://github.com/mailsac/cypress-mailsac/blob/main/examples/password-reset/README.md

Starts the example server with SMTP credentials from the local .env.smtp file. Requires copying .env.smtp.example to .env.smtp and filling it in locally. The app reads credentials from the local environment file; the Mailsac API key is used only by Node-side tasks, never placed in Cypress.env() or delivered to the application browser.

```sh
node --env-file=examples/password-reset/.env.smtp examples/password-reset/server.cjs

```

--------------------------------

### Run example app manually

Source: https://github.com/mailsac/cypress-mailsac/blob/main/examples/password-reset/README.md

Starts the example app for manual inspection. Open http://127.0.0.1:3037 to view the demonstration email address and initial password. In the default fixture mode, messages stay in memory rather than arriving in a real inbox.

```sh
npm run example

```

--------------------------------

### Run offline end-to-end tests

Source: https://github.com/mailsac/cypress-mailsac/blob/main/examples/password-reset/README.md

Installs dependencies, builds the package, and runs the end-to-end Cypress test suite. The runner starts the app on a free loopback port, runs Cypress headlessly, and stops the app. It uses a local fixture that implements the Mailsac API endpoints the plugin needs; it sends no email, uses no real key, and makes no calls to Mailsac.

```sh
npm ci
npm run build
npm run test:e2e

```

--------------------------------

### Install dependencies and run tests

Source: https://github.com/mailsac/cypress-mailsac/blob/main/README.md

Run these commands in order to install dependencies, run unit tests, run end-to-end tests with Cypress, and preview the package contents. Unit tests cover matching, stale mail, timeouts, authorization failures, retries, path encoding, and safe error handling. Default tests never call production or send real email.

```sh
npm ci
npm test
npm run test:e2e
npm pack --dry-run
```

--------------------------------

### Install @mailsac/cypress

Source: https://github.com/mailsac/cypress-mailsac/blob/main/README.md

Install the Mailsac Cypress plugin as a dev dependency. Requires Cypress 16 and a Node.js version supported by Cypress (22, 24, or 26+).

```sh
npm install --save-dev @mailsac/cypress
```

--------------------------------

### Run live Cypress test with real inbox

Source: https://github.com/mailsac/cypress-mailsac/blob/main/examples/password-reset/README.md

Runs the explicit live Cypress test against a real Mailsac inbox. Requires the app to be running in another terminal and the .env.smtp file to be configured. The Mailsac API key is used only by Node-side tasks, never placed in Cypress.env() or delivered to the application browser. Recordings and automatic failure screenshots are disabled in this example because reset tokens appear in the app URL.

```sh
node --env-file=examples/password-reset/.env.smtp node_modules/cypress/bin/cypress run --config-file examples/password-reset/cypress.config.cjs

```

--------------------------------

### Test a password reset with mailsacWaitForMessage and extractLink

Source: https://github.com/mailsac/cypress-mailsac/blob/main/README.md

Example test that waits for a password-reset email, extracts the reset link, and completes the reset. Replace the inbox, origin, subject, and selectors with your application's values. Use a test inbox you control and an API key authorized to read its bodies. Reset links are sensitive: use a private inbox or owned domain, and avoid recording live tokens in screenshots, videos, or logs.

```js
import { extractLink } from '@mailsac/cypress';

it('resets a password', () => {
  const email = 'your-test-inbox@mailsac.com';
  const origin = 'http://localhost:3000';

  cy.visit(`${origin}/forgot-password`);
  cy.get('[name=email]').type(email);

  cy.then(() => {
    // Capture immediately before triggering the email, not before a long setup.
    const receivedAfter = new Date().toISOString();
    cy.get('button[type=submit]').click();
    return cy.mailsacWaitForMessage({
      email,
      receivedAfter,
      subject: 'Reset your password',
      timeoutMs: 60_000,
    });
  }).then((message) => {
    const resetLink = extractLink(message, { origin, pathname: '/reset-password' });
    cy.visit(resetLink, { log: false });
    cy.get('[name=password]').type('A-new-test-password-123!', { log: false });
    cy.get('button[type=submit]').click();
    cy.contains('Password updated').should('be.visible');
  });
});
```

--------------------------------

### createMailsacTasks(options?)

Source: https://github.com/mailsac/cypress-mailsac/blob/main/README.md

Node.js entry point to create Mailsac Cypress tasks with configurable options.

```APIDOC
## createMailsacTasks(options?) — Node only

### Description
Creates Cypress tasks for Mailsac operations, intended for use in Node.js (Cypress plugins). It accepts configuration options and provides a `mailsac:waitForMessage` task.

### Method
Node.js function (not HTTP)

### Parameters
#### Options
- **apiKey** (string) - Optional - Default `process.env.MAILSAC_API_KEY`.
- **baseUrl** (string) - Optional - Default `https://mailsac.com/api`.
- **timeoutMs** (number) - Optional - Default timeout for tasks.
- **pollIntervalMs** (number) - Optional - Default poll interval for tasks.

### Usage
Direct `cy.task('mailsac:waitForMessage', criteria, { log: false, timeout: 130000 })` callers can use those defaults. The convenience command uses its own 30-second timeout unless given `timeoutMs` explicitly.

### Notes
HTTPS is required except for loopback fixtures. API redirects are disabled so a redirect cannot forward the key. HTTP 401/403 errors fail immediately; 429 and 5xx responses retry within the total deadline, respecting `Retry-After`. Other request failures fail promptly. Errors omit credentials and response bodies.
```

--------------------------------

### Register Mailsac tasks in cypress.config.js

Source: https://github.com/mailsac/cypress-mailsac/blob/main/README.md

Register the Mailsac tasks in cypress.config.js. The createMailsacTasks() function reads process.env.MAILSAC_API_KEY in Node; do not use a CYPRESS_ prefix or put the key in Cypress.env()/config.env.

```js
const { defineConfig } = require('cypress');
const { createMailsacTasks } = require('@mailsac/cypress/node');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('task', createMailsacTasks()); // Reads process.env.MAILSAC_API_KEY in Node.
      return config;
    },
  },
});
```

--------------------------------

### Import Mailsac commands in support file

Source: https://github.com/mailsac/cypress-mailsac/blob/main/README.md

Import the Mailsac Cypress commands in cypress/support/e2e.js (or .ts) to enable the custom commands.

```js
import '@mailsac/cypress/commands';
```

--------------------------------

### cy.mailsacWaitForMessage(options)

Source: https://github.com/mailsac/cypress-mailsac/blob/main/README.md

Cypress command to wait for a message in a Mailsac inbox and retrieve its content.

```APIDOC
## cy.mailsacWaitForMessage(options)

### Description
Waits for a message matching the given criteria in a Mailsac inbox, then returns its full metadata and text. This is a Cypress command intended for dedicated test inboxes.

### Method
Cypress command (not HTTP)

### Parameters
#### Options
- **email** (string) - Required - Recipient inbox.
- **receivedAfter** (string) - Required - ISO timestamp with timezone. Only messages received at or after this time qualify.
- **subject** (string) - Optional - Exact, case-sensitive subject.
- **subjectIncludes** (string) - Optional - Case-sensitive subject substring.
- **from** (string) - Optional - Sender email address, compared case-insensitively.
- **timeoutMs** (number) - Optional - Total time including HTTP requests and retries; default 30,000 ms, maximum 120,000 ms.
- **pollIntervalMs** (number) - Optional - Poll interval; default 1,000 ms, minimum 250 ms, maximum 10,000 ms.

At least one of `subject`, `subjectIncludes`, or `from` is required. All supplied filters must match. The newest matching message among the latest 100 messages is selected; its full metadata and text are then fetched.

### Returns
Returns `{ _id, subject, received, to, from, links, text }`. Recipients use `{ address, name? }`.

### Notes
The task does not delete mail, change inbox settings, or send email. Polling and body/metadata reads consume Mailsac API operations.
```

--------------------------------

### extractCode(message, options?)

Source: https://github.com/mailsac/cypress-mailsac/blob/main/README.md

Helper to extract a single distinct code from a message, with configurable pattern and flags.

```APIDOC
## extractCode(message, options?)

### Description
Extracts one distinct code from the message text. By default, it looks for a standalone six-digit code. Optional pattern, flags, and capture group allow other formats.

### Method
Helper function (not HTTP)

### Parameters
#### Arguments
- **message** (object) - Required - The message object returned by `cy.mailsacWaitForMessage`.
- **options** (object) - Optional - Configuration for extraction.
  - **pattern** (string) - Optional - Regular expression pattern. Default: `\b\d{6}\b`.
  - **flags** (string) - Optional - Regular expression flags. Supported flags are `i`, `m`, `s`, and `u`.
  - **group** (number) - Optional - Capture group index. Default: 0.

### Returns
Returns one distinct code string.

### Notes
Helpers fail if no match or more than one distinct match is found; they never guess between different links or codes. Patterns are test-author configuration, not untrusted user input.
```

--------------------------------

### Extract one-time code from email with cy.mailsacWaitForMessage

Source: https://github.com/mailsac/cypress-mailsac/blob/main/README.md

Waits for a verification email and extracts a six-digit code to type into a form field. Requires a `receivedAfter` ISO timestamp and a subject; `extractCode` fails if no match or more than one distinct match is found.

```javascript
import { extractCode } from '@mailsac/cypress';

cy.mailsacWaitForMessage({
  email: 'your-test-inbox@mailsac.com',
  receivedAfter,
  subject: 'Your verification code',
}).then((message) => {
  const code = extractCode(message); // One distinct standalone six-digit code.
  cy.get('[name=code]').type(code, { log: false });
});
```

--------------------------------

### extractLink(message, { origin, pathname? })

Source: https://github.com/mailsac/cypress-mailsac/blob/main/README.md

Helper to extract a single distinct link from a message with origin and optional pathname filtering.

```APIDOC
## extractLink(message, { origin, pathname? })

### Description
Extracts one distinct HTTP(S) URL from a message that matches the given origin and optional pathname. It rejects missing or ambiguous results and URLs containing credentials.

### Method
Helper function (not HTTP)

### Parameters
#### Arguments
- **message** (object) - Required - The message object returned by `cy.mailsacWaitForMessage`.
- **origin** (string) - Required - The exact origin of the URL to extract.
- **pathname** (string) - Optional - Exact pathname to match.

### Returns
Returns one distinct HTTP(S) URL string.

### Notes
Restrict the pathname to exclude same-origin help pages and other unrelated links to your app.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.