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

# Mails.so plugin

> Email address validation with Mails.so - check one address for deliverability, start a batch validation job for a list, and read the job back with its per-address results.

Use **Mails.so** through Corsair: one client, typed API calls.

Sign up at mails.so for an API key (see [https://docs.mails.so/authentication](https://docs.mails.so/authentication)). The key goes in the `x-mails-api-key` header; the plugin sends it there and nowhere else. Things to know before you send:

* **Single validation.** `validations.single` takes one address and returns its verdict (`result`, `reason`, a 0-100 `score`) plus the format, domain, MX, block-list, catch-all, generic, disposable and free-provider checks. A malformed address is not an error: Mails.so answers it as `undeliverable` with reason `invalid_format`. The `result` values are `deliverable`, `undeliverable`, `risky` and a fourth for checks that could not finish. They stay plain strings, so a value Mails.so adds later does not fail a call.
* **Test and placeholder domains.** `example.com` addresses come back `undeliverable` with reason `invalid_domain` and `is_disposable: true`.
* **Batch validation is asynchronous.** `validations.batch` starts a job and returns it at once, with its `id` and a `pending` status but no results. Read it with `validations.getBatch` using that `id`. While the job runs, the read answers with `status: 'processing'` and only the `id` and `created_at`; when it is done, `status` is `completed` and the job carries `stats` (counts per verdict and reason) and `emails` (one validation per address). Mails.so documents no failed status and no way to cancel or delete a job, so poll until `completed` and decide your own timeout.
* **A batch needs at least 2 different addresses.** Mails.so refuses a smaller one with a 400 and code `BATCH_TOO_SMALL`; the plugin checks this before sending. Use `validations.single` for one address.
* **Batch may need a paid plan.** Mails.so documents batch validation as paid-plan only, but a free account with credits started and finished a batch in our test on 2026-11-11. An account Mails.so refuses gets `MailssoSubscriptionRequiredError` ("Paid subscription required to use list validations"), which is not retried. That error text is the documented one; we have not seen it live.
* **A batch is a write.** `validations.batch` starts a job on your account, and Mails.so documents no way to delete one, so it is not retried after a server error or a dropped connection.
* **Errors.** Failures arrive as `{ data: null, error: '<message>' }`, and the plugin throws `MailssoAPIError` with that message. A 200 response whose `error` is set is treated as a failure too.
* **Webhooks.** Mails.so sends none, so the plugin does not receive webhooks.

**What you get:**

* 3 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/mailsso better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/mailsso better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/mailsso better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/mailsso better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { mailsso } from '@corsair-dev/mailsso';

export const corsair = createCorsair({
	plugins: [
		mailsso(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the Mails.so API key before the first call: `pnpm corsair setup --plugin=mailsso --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> mailsso()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'mailsso',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**Validate an email address**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.mailsso.api.validations.single({ email: 'hello@example.com' });
```

**Start a batch validation**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.mailsso.api.validations.batch({
	emails: ['first@example.com', 'second@example.com'],
});
```

See the full list on the [API](https://docs.corsair.dev/plugins/mailsso/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/mailsso/api.md)
>
> Every `mailsso.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.