@rhucodes/mailguard

Typed client for the mailguard disposable-email validation API, with the fail-open contract built in. Private package requires npm access to the @rhucodes scope.

Install

pnpm add @rhucodes/mailguard

Zero runtime dependencies. Node 18+, Cloudflare Workers, and other fetch-capable runtimes.

Usage

import { createMailguard } from '@rhucodes/mailguard'

const mailguard = createMailguard({ apiKey: process.env.MAILGUARD_API_KEY })

// In a signup flow — never throws, allows on any failure:
const result = await mailguard.checkSafe(email)

if (result.verdict === 'block') {
	// reject the signup; result.reason is 'disposable' or 'no_mx'
}

if (result.failedOpen) {
	// mailguard was unreachable — signup proceeded; result.error says why
}

checkSafe embeds the agreed contract: an 800ms default timeout and fail open on anything, timeouts, network errors, 5xx, even a misconfigured API key. A mailguard outage must never block a real signup.

Other methods

await mailguard.check(email) // raw call — throws MailguardError on failure
await mailguard.list() // { count, updatedAt, domains, wildcards } (~3MB, 30s timeout)
await mailguard.listVersion() // { count, updatedAt, sources }

Use list() to keep a local cache as your deeper fallback; wildcard entries match the domain itself and any subdomain.

Options

createMailguard({
	apiKey: '...', // required
	baseUrl: 'https://...', // default: production deployment
	timeoutMs: 800, // default check/listVersion timeout
	fetch: customFetch, // injectable for tests/polyfills
})

Per-call: { signal, timeoutMs } as the last argument of any method.