x-mails-api-key header; the plugin sends it there and nowhere else. Things to know before you send:
- Single validation.
validations.singletakes one address and returns its verdict (result,reason, a 0-100score) 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 asundeliverablewith reasoninvalid_format. Theresultvalues aredeliverable,undeliverable,riskyand 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.comaddresses come backundeliverablewith reasoninvalid_domainandis_disposable: true. - Batch validation is asynchronous.
validations.batchstarts a job and returns it at once, with itsidand apendingstatus but no results. Read it withvalidations.getBatchusing thatid. While the job runs, the read answers withstatus: 'processing'and only theidandcreated_at; when it is done,statusiscompletedand the job carriesstats(counts per verdict and reason) andemails(one validation per address). Mails.so documents no failed status and no way to cancel or delete a job, so poll untilcompletedand 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. Usevalidations.singlefor 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.batchstarts 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 throwsMailssoAPIErrorwith that message. A 200 response whoseerroris set is treated as a failure too. - Webhooks. Mails.so sends none, so the plugin does not receive webhooks.
- 3 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Mails.so API key before the first call: More: API Key
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.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.
Example API calls
Validate an email addressWhat’s next
API reference
Every
mailsso.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.