adonis-email-guard

AdonisJS v5 package for email validation and a DB-backed suppression list.

• Syntax / MX / disposable / spam-trap / optional SMTP RCPT-TO checks
• Suppression CRUD with configurable table name
• Suppression table auto-created on boot (opt-out via config)
• Single IoC binding: @ioc:Adonis/Addons/EmailGuard

Install

npm i adonis-email-guard
node ace configure adonis-email-guard

The configure step copies config/email-guard.ts into your app and registers the provider.

Configuration

config/email-guard.ts:

import {EmailGuardConfig} from '@ioc:Adonis/Addons/EmailGuard';

const emailGuardConfig: EmailGuardConfig = {
  tableName: 'email_suppressions',
  autoCreateTable: true,
  // connection: 'primary',
  validator: {
    checkSmtp: false,
    smtpTimeoutMs: 5000,
  },
  extraDisposableDomains: [],
  extraSpamTrapDomains: [],
};

export default emailGuardConfig;

Usage

import EmailGuard from '@ioc:Adonis/Addons/EmailGuard';

// validate only
const v = await EmailGuard.validate('user@gmial.com');
// v.valid → false, v.suggestion → 'user@gmail.com'

// validate + suppression lookup in one call
const c = await EmailGuard.check('user@example.com', {recordFailures: true});
if (!c.valid || c.suppressed) return; // do not send

// suppression CRUD
await EmailGuard.suppress('bounce@x.com', 'bounce', 'webhook', {provider: 'postmark'});
await EmailGuard.isSuppressed('bounce@x.com'); // true
await EmailGuard.find('bounce@x.com');
await EmailGuard.list({reason: 'bounce', limit: 50});
await EmailGuard.count({source: 'webhook'});
await EmailGuard.unsuppress('bounce@x.com');

API

validate(email, options?)

Option	Default	Notes
checkSmtp	false	RCPT-TO probe on the MX host. Many networks block port 25.
fromAddress	derived	MAIL FROM value when checkSmtp is true.
smtpTimeoutMs	5000	Per-step socket timeout.

Returns { valid, email, reason?, checks, suggestion?, mxHost? }.

check(email, options?)

validate + suppression lookup. With recordFailures: true, failures are inserted into the suppression list with source: 'validator'.

Suppression

Method	Description
suppress(email, reason?, source?, metadata?)	Upsert.
unsuppress(email)	Delete. Returns true if a row was removed.
isSuppressed(email)	Boolean lookup.
find(email)	Row or null.
list(filters?)	Filter by reason/source/search, with paging.
count(filters?)	Same filters, returns a count.
ensureTable()	Idempotent CREATE TABLE IF NOT EXISTS.

Suppression table schema

Column	Type
id	bigint, PK
email	varchar(320), unique
reason	varchar(64), nullable, indexed
source	varchar(64), nullable, indexed
metadata	json, nullable
created_at	timestamptz
updated_at	timestamptz

License

MIT