addrly

Official Node.js SDK for the Addrly email validation API.

Install

npm install addrly

Quick Start

import { Addrly } from 'addrly';

const addrly = new Addrly('sk_your_api_key');

// Validate an email
const result = await addrly.validateEmail('user@example.com');
console.log(result.mx, result.disposable, result.domain_age_in_days);

// Validate a domain
const domain = await addrly.validateDomain('example.com');

// Auto-detect (email or domain)
const auto = await addrly.validate('test@gmail.com');

Bulk Validation

// Bulk email validation (Pro: 500, Ultra: 1000)
const bulk = await addrly.bulkValidateEmails([
  'user1@gmail.com',
  'user2@yahoo.com',
  'spam@tempmail.com',
]);
console.log(bulk.summary); // { total: 3, valid: 2, invalid: 1, ... }

// Bulk domain validation
const domains = await addrly.bulkValidateDomains([
  'gmail.com',
  'tempmail.com',
]);

Gates

// Evaluate an email against a gate
const decision = await addrly.gate('gate_abc123def456', {
  email: 'user@tempmail.com',
});

console.log(decision.decision.action); // 'block'
console.log(decision.decision.matched_rule?.name); // 'Block disposable emails'

Configuration

const addrly = new Addrly({
  apiKey: 'sk_your_api_key',
  baseUrl: 'https://api.addrly.app', // default
  timeout: 30000, // ms, default
});

Error Handling

try {
  const result = await addrly.validateEmail('test@example.com');
} catch (err) {
  console.error(err.status);   // 429
  console.error(err.message);  // 'Rate limit exceeded'
  console.error(err.response); // full API error response
}

Environments

// Validate against a specific environment's blocklist
const result = await addrly.validateEmail('user@blocked.com', {
  environment: 'production',
});

TypeScript

Full TypeScript support with exported types:

import { Addrly, EmailValidationResult, GateDecisionResult } from 'addrly';

Requirements

• Node.js 18+ (uses native fetch)
• No external dependencies

Links

• Documentation
• Dashboard
• API Reference