Structured Errors & Delivery States

MailPort provides explicit error classes with retryable flags, delivery certainty classifications, and automatic credential redaction.

Delivery States

• not-sent: Connection or validation failed before transmission. Safe to retry immediately.
• rejected: Server explicitly rejected sender, recipient, or body payload. Do not retry without fixing the root cause.
• uncertain: Socket disconnected after DATA payload transmission before final 250 response. Do NOT retry automatically to prevent duplicate emails.

Error Hierarchy

import {
  MailError,
  MailAuthError,
  MailConnectionError,
  MailUncertainError,
} from 'mailport';

try {
  await mailer.send(message);
} catch (err) {
  if (err instanceof MailAuthError) {
    console.error('SMTP credentials rejected');
  } else if (err instanceof MailConnectionError) {
    console.error('Connection failed prior to send. Retryable:', err.retryable);
  } else if (err instanceof MailUncertainError) {
    console.error('Network lost after body payload. Delivery status uncertain.');
  }
}