smartmta/dist_ts/mail/core/classes.bouncemanager.d.ts

import type { Email } from './classes.email.js';
/**
 * Bounce types for categorizing the reasons for bounces
 */
export declare enum BounceType {
    INVALID_RECIPIENT = "invalid_recipient",
    DOMAIN_NOT_FOUND = "domain_not_found",
    MAILBOX_FULL = "mailbox_full",
    MAILBOX_INACTIVE = "mailbox_inactive",
    BLOCKED = "blocked",
    SPAM_RELATED = "spam_related",
    POLICY_RELATED = "policy_related",
    SERVER_UNAVAILABLE = "server_unavailable",
    TEMPORARY_FAILURE = "temporary_failure",
    QUOTA_EXCEEDED = "quota_exceeded",
    NETWORK_ERROR = "network_error",
    TIMEOUT = "timeout",
    AUTO_RESPONSE = "auto_response",
    CHALLENGE_RESPONSE = "challenge_response",
    UNKNOWN = "unknown"
}
/**
 * Hard vs soft bounce classification
 */
export declare enum BounceCategory {
    HARD = "hard",
    SOFT = "soft",
    AUTO_RESPONSE = "auto_response",
    UNKNOWN = "unknown"
}
/**
 * Bounce data structure
 */
export interface BounceRecord {
    id: string;
    originalEmailId?: string;
    recipient: string;
    sender: string;
    domain: string;
    subject?: string;
    bounceType: BounceType;
    bounceCategory: BounceCategory;
    timestamp: number;
    smtpResponse?: string;
    diagnosticCode?: string;
    statusCode?: string;
    headers?: Record<string, string>;
    processed: boolean;
    retryCount?: number;
    nextRetryTime?: number;
}
/**
 * Retry strategy configuration for soft bounces
 */
interface RetryStrategy {
    maxRetries: number;
    initialDelay: number;
    maxDelay: number;
    backoffFactor: number;
}
/**
 * Manager for handling email bounces
 */
export declare class BounceManager {
    private retryStrategy;
    private bounceStore;
    private bounceCache;
    private suppressionList;
    private storageManager?;
    constructor(options?: {
        retryStrategy?: Partial<RetryStrategy>;
        maxCacheSize?: number;
        cacheTTL?: number;
        storageManager?: any;
    });
    /**
     * Process a bounce notification
     * @param bounceData Bounce data to process
     * @returns Processed bounce record
     */
    processBounce(bounceData: Partial<BounceRecord>): Promise<BounceRecord>;
    /**
     * Process an SMTP failure as a bounce
     * @param recipient Recipient email
     * @param smtpResponse SMTP error response
     * @param options Additional options
     * @returns Processed bounce record
     */
    processSmtpFailure(recipient: string, smtpResponse: string, options?: {
        sender?: string;
        originalEmailId?: string;
        statusCode?: string;
        headers?: Record<string, string>;
    }): Promise<BounceRecord>;
    /**
     * Process a bounce notification email
     * @param bounceEmail The email containing bounce information
     * @returns Processed bounce record or null if not a bounce
     */
    processBounceEmail(bounceEmail: Email): Promise<BounceRecord | null>;
    /**
     * Handle a hard bounce by adding to suppression list
     * @param bounce The bounce record
     */
    private handleHardBounce;
    /**
     * Handle a soft bounce by scheduling a retry if eligible
     * @param bounce The bounce record
     */
    private handleSoftBounce;
    /**
     * Add an email address to the suppression list
     * @param email Email address to suppress
     * @param reason Reason for suppression
     * @param expiresAt Expiration timestamp (undefined for permanent)
     */
    addToSuppressionList(email: string, reason: string, expiresAt?: number): void;
    /**
     * Remove an email address from the suppression list
     * @param email Email address to remove
     */
    removeFromSuppressionList(email: string): void;
    /**
     * Check if an email is on the suppression list
     * @param email Email address to check
     * @returns Whether the email is suppressed
     */
    isEmailSuppressed(email: string): boolean;
    /**
     * Get suppression information for an email
     * @param email Email address to check
     * @returns Suppression information or null if not suppressed
     */
    getSuppressionInfo(email: string): {
        reason: string;
        timestamp: number;
        expiresAt?: number;
    } | null;
    /**
     * Save suppression list to disk
     */
    private saveSuppressionList;
    /**
     * Load suppression list from disk
     */
    private loadSuppressionList;
    /**
     * Save bounce record to disk
     * @param bounce Bounce record to save
     */
    private saveBounceRecord;
    /**
     * Update bounce cache with new bounce information
     * @param bounce Bounce record to update cache with
     */
    private updateBounceCache;
    /**
     * Check bounce history for an email address
     * @param email Email address to check
     * @returns Bounce information or null if no bounces
     */
    getBounceInfo(email: string): {
        lastBounce: number;
        count: number;
        type: BounceType;
        category: BounceCategory;
    } | null;
    /**
     * Analyze SMTP response and diagnostic codes to determine bounce type
     * @param smtpResponse SMTP response string
     * @param diagnosticCode Diagnostic code from bounce
     * @param statusCode Status code from bounce
     * @returns Detected bounce type and category
     */
    private detectBounceType;
    /**
     * Check if text matches any pattern for a bounce type
     * @param text Text to check against patterns
     * @param bounceType Bounce type to get patterns for
     * @returns Whether the text matches any pattern
     */
    private matchesPattern;
    /**
     * Get all known hard bounced addresses
     * @returns Array of hard bounced email addresses
     */
    getHardBouncedAddresses(): string[];
    /**
     * Get suppression list
     * @returns Array of suppressed email addresses
     */
    getSuppressionList(): string[];
    /**
     * Clear old bounce records (for maintenance)
     * @param olderThan Timestamp to remove records older than
     * @returns Number of records removed
     */
    clearOldBounceRecords(olderThan: number): number;
}
export {};