Validate emails in Segment

{
  "ev_status": "valid",
  "ev_reason": "accepted",
  "ev_action": "send",
  "ev_processed_at": "2026-11-06T12:00:00.000Z"
}

// email-validation.org for Segment 1.0.0: a Segment Function (paste it as a destination function or an insert function).
// Docs: https://email-validation.org/docs/guides/segment/
//
// It checks the address of identify events (traits.email) and of the track events you name, and adds the result to
// the event as ev_status, ev_reason, ev_action and ev_processed_at. Each checked event costs one credit (results
// with status unknown and test addresses are free): Segment Functions keep no lasting state, so the function cannot
// tell whether an address changed. A cache inside the function saves repeat checks of the same address only while
// Segment keeps the function's process running.
//
// Settings (Settings tab of the function):
//   apiKey          Secret, required. Your email-validation.org API key (give it a daily credit cap).
//   region          Optional. "eu" for EU data residency; anything else is US.
//   checkIdentify   Optional boolean. false: identify events are not checked (default: checked).
//   trackEvents     Optional. Comma-separated track event names to check, e.g. "Signed Up, Email Changed".
//   writeKey        Secret, optional. A Segment HTTP API source's write key: the result is also sent there as an
//                   identify call with the ev_ traits (never the address), for your profiles and warehouse.
//   writeKeyRegion  Optional. "eu" when that source's workspace is in the EU.
//   retryLater      Optional boolean. true: a rate limit (429) or outage (503) throws RetryError, so Segment tries the
//                   event again later. Use it only in a destination function: in an insert function a retried
//                   event reaches its destination late. Default: the event goes on unchecked.
//
// A problem on our side never stops your events: the event goes on without the ev_ traits, and one log line says
// why (never the address).

const EV_VERSION = '1.0.0';
const EV_USER_AGENT = `email-validation-segment-function/${EV_VERSION}`;
const EV_ORIGINS = { us: 'https://api.email-validation.org', eu: 'https://api-eu.email-validation.org' };
const EV_SEGMENT_IDENTIFY = {
  us: 'https://api.segment.io/v1/identify',
  eu: 'https://events.eu1.segmentapis.com/v1/identify',
};
const EV_STATUSES = ['valid', 'invalid', 'catch_all', 'unknown', 'disposable'];
// Our API answers within this many seconds (its shortest wait; a slower check is unknown, reason timeout, free).
const EV_CHECK_TIMEOUT_S = 5;
// Segment stops a function after 5 seconds: the check and the write-back each get a share of that.
const EV_CHECK_LIMIT_MS = 3800;
const EV_WRITE_BACK_LIMIT_MS = 900;
// How long a result is kept in the function's cache (process-local; Segment may empty it at any time).
const EV_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
// After a 429 or 503 without Retry-After, no check is sent for this long.
const EV_DEFAULT_PAUSE_S = 30;

// Until when no check is sent, after our API asked to wait (Retry-After). Process-local.
let evPausedUntil = 0;

// biome-ignore lint/correctness/noUnusedVariables: Segment calls each handler by its name
async function onIdentify(event, settings) {
  if (settings.checkIdentify === false || settings.checkIdentify === 'false') return event;
  const email = evAddress(event.traits);
  if (!email) return event;
  const verdict = await evCheck(email, settings);
  if (!verdict) return event;
  event.traits = Object.assign({}, event.traits, verdict);
  await evWriteBack(event, verdict, settings);
  return event;
}

// biome-ignore lint/correctness/noUnusedVariables: Segment calls each handler by its name
async function onTrack(event, settings) {
  if (!evNamed(settings.trackEvents, event.event)) return event;
  const email = evAddress(event.properties) || evAddress(event.context?.traits);
  if (!email) return event;
  const verdict = await evCheck(email, settings);
  if (!verdict) return event;
  event.properties = Object.assign({}, event.properties, verdict);
  await evWriteBack(event, verdict, settings);
  return event;
}

// An insert function blocks every event type it has no handler for: these pass the others on unchanged.
// biome-ignore lint/correctness/noUnusedVariables: Segment calls each handler by its name
async function onPage(event) {
  return event;
}
// biome-ignore lint/correctness/noUnusedVariables: Segment calls each handler by its name
async function onScreen(event) {
  return event;
}
// biome-ignore lint/correctness/noUnusedVariables: Segment calls each handler by its name
async function onGroup(event) {
  return event;
}
// biome-ignore lint/correctness/noUnusedVariables: Segment calls each handler by its name
async function onAlias(event) {
  return event;
}
// biome-ignore lint/correctness/noUnusedVariables: Segment calls each handler by its name
async function onDelete(event) {
  return event;
}

function evAddress(traits) {
  const value = traits && typeof traits.email === 'string' ? traits.email.trim() : '';
  return value.includes('@') ? value : '';
}

function evNamed(list, name) {
  if (typeof list !== 'string' || typeof name !== 'string') return false;
  return list
    .split(',')
    .map((s) => s.trim())
    .filter(Boolean)
    .includes(name);
}

function evLog(message) {
  console.log(`email-validation.org: ${message}`);
}

function evIsTrue(value) {
  return value === true || value === 'true';
}

// The result as traits, or null when the address was not checked (the reason is logged).
async function evCheck(email, settings) {
  const apiKey = typeof settings.apiKey === 'string' ? settings.apiKey.trim() : '';
  if (!apiKey || /\s/.test(apiKey)) {
    evLog('not checked: the apiKey setting is missing.');
    return null;
  }
  if (Date.now() < evPausedUntil) return evLimited(settings, 'paused after a rate limit');
  const region = settings.region === 'eu' ? 'eu' : 'us';
  const load = () => evValidate(EV_ORIGINS[region], apiKey, email, settings);
  if (typeof cache === 'undefined' || !cache || typeof cache.load !== 'function') return load();
  const key = `ev:${region}:${email.toLowerCase()}`;
  const verdict = await cache.load(key, EV_CACHE_TTL_MS, load);
  // Only charged results are kept: unknown is free and always checked again; null means not checked.
  if (!verdict || verdict.ev_status === 'unknown') cache.delete(key);
  return verdict;
}

async function evValidate(origin, apiKey, email, settings) {
  let response;
  try {
    response = await fetch(`${origin}/v1/validate`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
        Accept: 'application/json',
        'User-Agent': EV_USER_AGENT,
      },
      body: JSON.stringify({ email: email, timeout: EV_CHECK_TIMEOUT_S }),
      redirect: 'manual',
      timeout: EV_CHECK_LIMIT_MS,
      signal: evSignal(EV_CHECK_LIMIT_MS),
    });
  } catch {
    // Never retried: the check may have run and been charged, and a retry would charge it again.
    evLog('not checked: no answer from the API in time (not retried).');
    return null;
  }
  let body = null;
  try {
    body = await response.json();
  } catch {
    body = null;
  }
  if (response.status === 200 && body && EV_STATUSES.includes(body.status)) {
    return {
      ev_status: body.status,
      ev_reason: typeof body.reason === 'string' ? body.reason : '',
      ev_action: typeof body.action === 'string' ? body.action : '',
      ev_processed_at: typeof body.processed_at === 'string' ? body.processed_at : '',
    };
  }
  const error = body?.error ? body.error : {};
  const code = typeof error.code === 'string' ? error.code : 'unexpected_response';
  const requestId = typeof error.request_id === 'string' ? error.request_id : response.headers.get('x-request-id');
  const where = ` (HTTP ${response.status}, ${code}${requestId ? `, request ${requestId}` : ''})`;
  if ((response.status === 429 || response.status === 503) && code !== 'key_daily_cap') {
    const after = evRetryAfter(response.headers.get('retry-after'));
    evPausedUntil = Date.now() + (after === null ? EV_DEFAULT_PAUSE_S : after) * 1000;
    return evLimited(settings, `rate limited${where}`);
  }
  evLog(`not checked${where}.`);
  return null;
}

// A rate limit: with retryLater, Segment tries the event again later (nothing was charged); else it goes on unchecked.
function evLimited(settings, why) {
  if (evIsTrue(settings.retryLater)) throw new RetryError(`email-validation.org: ${why}; Segment retries later.`);
  evLog(`not checked: ${why}.`);
  return null;
}

function evRetryAfter(value) {
  if (typeof value !== 'string' || value.trim() === '') return null;
  if (/^\d+$/.test(value.trim())) return Number(value.trim());
  const at = Date.parse(value);
  return Number.isNaN(at) ? null : Math.max(0, Math.ceil((at - Date.now()) / 1000));
}

function evSignal(ms) {
  return typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
    ? AbortSignal.timeout(ms)
    : undefined;
}

// The result to the customer's own Segment source: ids and ev_ traits only, never the address, so the call has
// nothing for this function to check if that source feeds it too (no loop, no charge). Never retried: the check was
// already charged.
async function evWriteBack(event, verdict, settings) {
  const writeKey = typeof settings.writeKey === 'string' ? settings.writeKey.trim() : '';
  if (!writeKey) return;
  const userId = typeof event.userId === 'string' && event.userId ? event.userId : undefined;
  const anonymousId = typeof event.anonymousId === 'string' && event.anonymousId ? event.anonymousId : undefined;
  if (!userId && !anonymousId) return;
  const url = settings.writeKeyRegion === 'eu' ? EV_SEGMENT_IDENTIFY.eu : EV_SEGMENT_IDENTIFY.us;
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        Authorization: `Basic ${btoa(`${writeKey}:`)}`,
        'Content-Type': 'application/json',
        'User-Agent': EV_USER_AGENT,
      },
      body: JSON.stringify({ userId: userId, anonymousId: anonymousId, traits: verdict }),
      redirect: 'manual',
      timeout: EV_WRITE_BACK_LIMIT_MS,
      signal: evSignal(EV_WRITE_BACK_LIMIT_MS),
    });
    if (response.status < 200 || response.status >= 300) evLog(`write-back failed (HTTP ${response.status}).`);
  } catch {
    evLog('write-back failed (no answer).');
  }
}