nodemailer

Postconditions — what we check

• sendMail · connection-error

  error
  WhenNetwork connectivity issues (TCP connection failed, timeout, DNS failure)
  ThrowsError with code: ECONNECTION, ETIMEDOUT, EDNS, ESOCKET
  Required handlingCaller MUST catch connection errors. ECONNECTION: TCP connection failed or closed unexpectedly. ETIMEDOUT: Connection/greeting/socket timeout (defaults: 2min/30s/10min). EDNS: Hostname DNS resolution failed. ESOCKET: Low-level socket error from net/tls modules. These errors are TRANSIENT and RETRIABLE with exponential backoff.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[1]
• sendMail · authentication-failure

  error
  WhenSMTP authentication fails (wrong credentials, locked account, unsupported auth)
  ThrowsError with code: EAUTH, ENOAUTH, EOAUTH2
  Required handlingCaller MUST catch authentication errors. EAUTH: Invalid username/password, account locked, unsupported auth method. ENOAUTH: Authentication required but not configured. EOAUTH2: OAuth2 token refresh failed or invalid credentials. DO NOT RETRY - indicates configuration issue. Check SMTP credentials and account status.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[2]
• sendMail · tls-ssl-error

  error
  WhenTLS/SSL certificate validation fails or STARTTLS fails
  ThrowsError with code: ETLS, EREQUIRETLS
  Required handlingCaller MUST catch TLS errors. ETLS: Certificate validation failed, hostname mismatch, STARTTLS failed. EREQUIRETLS: RFC 8689 REQUIRETLS extension unsupported by server. DO NOT RETRY - indicates certificate or TLS configuration issue. Verify SSL certificate validity and STARTTLS support.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[3]
• sendMail · invalid-recipient

  error
  WhenRecipient email address is malformed or rejected
  ThrowsError with code: EENVELOPE
  Required handlingCaller MUST validate email addresses before sending. EENVELOPE: Invalid recipient format, missing from/to address, SMTP rejected. Validate against RFC 5321/5322 before calling sendMail(). Check info.rejected array for partial failures. SECURITY: Sanitize addresses to prevent CVE-2021-23400 (header injection).
  costmediumin prodimmediate exceptionusers seelost transactionvisibilitysilent
  Sources[4]
• sendMail · message-content-error

  error
  WhenMessage content is invalid or attachments fail to load
  ThrowsError with code: EMESSAGE, EFILEACCESS, EURLACCESS, EFETCH, ESTREAM
  Required handlingCaller MUST validate message content and attachments. EMESSAGE: Invalid message structure, encoding issues. EFILEACCESS: Attachment file not found or unreadable. EURLACCESS: Cannot fetch URL attachment. EFETCH: HTTP error fetching remote content. ESTREAM: Attachment stream failed. Verify attachment paths exist and are readable before sending.
  costlowin prodimmediate exceptionusers seelost transactionvisibilitysilent
  Sources[5]
• sendMail · protocol-error

  error
  WhenSMTP protocol violation or configuration error
  ThrowsError with code: EPROTOCOL, ECONFIG, EMAXLIMIT
  Required handlingCaller MUST handle protocol errors. EPROTOCOL: SMTP protocol error from server. ECONFIG: Invalid transport configuration. EMAXLIMIT: Message size exceeds server limit. Check SMTP server logs and message size limits.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[6]
• verify · verification-failure

  error
  WhenSMTP connection or authentication fails during verification
  ThrowsError with code: ECONNECTION, EAUTH, ETLS, EDNS, ETIMEDOUT
  Required handlingCaller MUST catch verification errors. Call verify() during application initialization to catch config issues early. Same error codes as sendMail() connection/auth errors. Verification failure indicates configuration problem - fix before deployment.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• createTransport · configuration-error

  info
  WhenInvalid transport configuration
  ReturnsTransporter instance (errors deferred to sendMail/verify)
  Required handlingNo try-catch needed for createTransport(). Configuration errors are deferred and surface when sendMail() or verify() is called. Best practice: call verify() after createTransport() to validate configuration early. Use environment variables for credentials, never hardcode.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[8]
• createTestAccount · create-test-account-network-error

  error
  WhenEthereal API (api.nodemailer.com) is unreachable or connection fails
  ThrowsError (no code) — raw ECONNREFUSED, ETIMEDOUT, ENOTFOUND from HTTP layer
  Required handlingCaller MUST catch network errors from createTestAccount(). Unlike sendMail(), this error has no structured code field — it is the raw network error from Node.js HTTP (ECONNREFUSED, ETIMEDOUT, ENOTFOUND). DO NOT use createTestAccount() in production app startup — if Ethereal API is down, it will crash your app initialization. BEST PRACTICE: Call createTestAccount() only in test setup scripts with full try/catch. Cache the result (it is already module-scoped by nodemailer).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[9]
• createTestAccount · create-test-account-api-error

  warning
  WhenEthereal API returns non-success status or error field in response
  ThrowsError with message from data.error or 'Request failed'
  Required handlingCaller MUST catch API-level errors. Ethereal API returns { status: 'error', error: 'message' } for failures including rate limits, server errors, and account creation failures. This error has no .code property — check err.message for details. RETRY: These errors are generally transient — retry after delay. FALLBACK: Use static test credentials (saved from a previous successful call) or configure a real test SMTP server (Mailhog, Mailtrap) instead of Ethereal.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[10]
• createTestAccount · create-test-account-parse-error

  warning
  WhenEthereal API returns invalid JSON (service outage, CDN error page)
  ThrowsSyntaxError (JSON parse failure)
  Required handlingCaller MUST catch SyntaxError from createTestAccount(). During Ethereal API outages, the response may be an HTML error page (Cloudflare 5xx, maintenance page) instead of JSON. JSON.parse() throws SyntaxError. Check err instanceof SyntaxError to distinguish from network/API errors. FALLBACK: Use hardcoded test SMTP credentials or local mail catcher.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[11]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]nodemailer.com/errorshttps://nodemailer.com/errors/#econnection
2. [2]nodemailer.com/errorshttps://nodemailer.com/errors/#eauth
3. [3]nodemailer.com/smtphttps://nodemailer.com/smtp/#tls-options
4. [4]nodemailer.com/errorshttps://nodemailer.com/errors/#eenvelope
5. [5]nodemailer.com/message/attachmentshttps://nodemailer.com/message/attachments/
6. [6]nodemailer.com/errorshttps://nodemailer.com/errors/#eprotocol
7. [7]nodemailer.com/usagehttps://nodemailer.com/usage/#verify-smtp-connection-configuration
8. [8]nodemailer.com/smtphttps://nodemailer.com/smtp/
9. [9]github.com/nodemailer/nodemailerhttps://github.com/nodemailer/nodemailer/blob/master/lib/nodemailer.js#L113
10. [10]github.com/nodemailer/nodemailerhttps://github.com/nodemailer/nodemailer/blob/master/lib/nodemailer.js#L123-L125
11. [11]github.com/nodemailer/nodemailerhttps://github.com/nodemailer/nodemailer/blob/master/lib/nodemailer.js#L118-L121