Lacspace Devs
← All packages

@lacspace/bounce

v1.0.0Mail Kit0 deps

Bounce, complaint and auto-reply classifier for email campaigns and webmail: parses RFC 3464 delivery status notifications (Reporting-MTA, Final-Recipient, Action, Status, Diagnostic-Code, Remote-MTA), RFC 5965 ARF spam complaints and RFC 3834 auto-replies (Auto-Submitted, X-Autoreply, Precedence, out-of-office subjects). Also reads plain-text vendor bounces with no DSN part (Gmail, Outlook/Microsoft 365, Zoho, Hostinger/Titan, Postfix, Exim, qmail). Maps RFC 3463 enhanced codes, SMTP reply codes and diagnostic text to hard/soft plus a category (mailbox_unknown, mailbox_full, domain_unknown, blocked_spam, blocked_policy, auth_failed, message_too_large, rate_limited, temporary, challenge) with a confidence score and a plain-English reason. Includes a small built-in MIME splitter for raw messages. Zero dependencies, isomorphic.

npm i @lacspace/bounce
View on npm ↗GitHub ↗

Usage

bounce.ts
import { parseBounce, isBounce, isAutoReply, isBounceSender, classifyStatus } from "@lacspace/bounce";

// A whole raw message (string or Uint8Array)…
const report = parseBounce(rawEmail);

// …or the pieces your mail parser already decoded.
const report2 = parseBounce({
  headers: message.headerBlock,          // the full header block as text
  text: message.text,
  html: message.html,
  parts: [{ contentType: "message/delivery-status", body: "…" }],
});

// {
//   kind: "hard",
//   category: "mailbox_unknown",
//   recipients: [{ address: "ghost@gmail.com", action: "failed", status: "5.1.1",
//                  diagnostic: "550-5.1.1 The email account that you tried to reach does not exist…",
//                  remoteMta: "gmail-smtp-in.l.google.com" }],
//   reportingMta: "mx.google.com",
//   originalMessageId: "<camp-42@shop.example>",
//   originalSubject: "October deals",
//   confidence: 0.95,
//   reason: "The mailbox ghost@gmail.com does not exist or has been disabled (status 5.1.1). Stop sending to this address."
// }

if (report?.kind === "hard" || report?.kind === "complaint") {
  for (const r of report.recipients) suppress(r.address);
}

Exports 9

categoryFromTextclassifyStatusextractAddressfindBasicCodefindEnhancedStatusisAutoReplyisBounceisBounceSenderparseBounce

Keywords

bouncebouncesdsnrfc3464rfc3463rfc5965

More in Mail Kit

@lacspace/email-templates

Compose bulletproof, responsive, dark-mode HTML emails from simple blocks, plus 13 ready-made transactional templates (OTP, verify, password-reset, magic-link, receipt, order, shipping, invitation, digest, announcement). Ships plaintext generation, preheaders and {{var}} i18n interpolation. Zero-dependency, isomorphic.

@lacspace/email-validate

Smart, network-free email validation — RFC-5322 syntax (incl. quoted local parts & IP-literal domains), disposable/temp-mail & role-account detection, free-provider flags, Gmail normalization and 'did you mean?' typo suggestions. Zero-dependency, isomorphic.

@lacspace/email-verify

Best-effort email deliverability for Node — syntax + disposable/role, MX lookup with priority ranking, an optional SMTP RCPT probe (no mail sent), catch-all detection, a 0-100 confidence score, and de-duped batch verification. All DNS/SMTP injectable; zero npm dependencies.

@lacspace/mailer

A tiny zero-dependency SMTP client for Node — send email over raw net/tls with STARTTLS & AUTH, plus a fluent MIME builder (inline images, attachments, alternatives), RFC 5322 address + RFC 2047 helpers, batch send with retry, and no-network test transports. Provider presets (Hostinger, Gmail, Outlook, Zoho…) make setup one line.

@lacspace/imap

Zero-dependency IMAP4rev1 client for Node (RFC 3501 + IDLE, MOVE, UIDPLUS, CONDSTORE, SPECIAL-USE, LIST-EXTENDED, LITERAL+, SASL-IR, QUOTA, ID). Implicit TLS and STARTTLS with verification on, LOGIN / PLAIN / XOAUTH2 / OAUTHBEARER, streaming byte-accurate parser, async-iterable FETCH, envelopes with RFC 2047 decoding, BODYSTRUCTURE trees shared with @lacspace/mime, modified UTF-7 mailbox names, special-use detection (incl. Gmail XLIST and localised names), IDLE with NOOP fallback. Works with Hostinger (Dovecot), Gmail, Outlook/Exchange, GoDaddy.

@lacspace/mime

Isomorphic RFC 5322 / RFC 2045-2049 MIME parser and builder for webmail. parseMime() turns raw mail (string or bytes) into from/to/cc/subject/date/text/html/attachments/inline cid images/priority/List-Unsubscribe one-click and the part tree; handles nested multipart (mixed, alternative, related, report, signed), message/rfc822 forwards, base64 and quoted-printable (tolerant), RFC 2047 encoded words (split multibyte, adjacent whitespace), RFC 2231 parameters, 30+ charsets and malformed input without ever throwing. parseBodyStructure() parses IMAP BODYSTRUCTURE (literals, extension data) into the same tree with IMAP partIds, plus findTextParts / listAttachments / decodePart for lazy fetching. buildMime() writes CRLF messages with encoded-word headers, QP/base64 bodies, mixed/alternative/related nesting, Message-ID generation and header-injection guards; replyHeaders() / forwardSubject() for threading. Pairs with @lacspace/imap and @lacspace/mailer. Zero dependencies; Node 18+, edge runtimes and browsers.

← Browse all 197 packagesRead the handbook