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

import * as plugins from '../../plugins.js';
export interface IAttachment {
    filename: string;
    content: Buffer;
    contentType: string;
    contentId?: string;
    encoding?: string;
}
export interface IEmailOptions {
    from: string;
    to?: string | string[];
    cc?: string | string[];
    bcc?: string | string[];
    subject: string;
    text: string;
    html?: string;
    attachments?: IAttachment[];
    headers?: Record<string, string>;
    mightBeSpam?: boolean;
    priority?: 'high' | 'normal' | 'low';
    skipAdvancedValidation?: boolean;
    variables?: Record<string, any>;
}
/**
 * Email class represents a complete email message.
 *
 * This class takes IEmailOptions in the constructor and normalizes the data:
 * - 'to', 'cc', 'bcc' are always converted to arrays
 * - Optional properties get default values
 * - Additional properties like messageId and envelopeFrom are generated
 */
export declare class Email {
    from: string;
    to: string[];
    cc: string[];
    bcc: string[];
    subject: string;
    text: string;
    html?: string;
    attachments: IAttachment[];
    headers: Record<string, string>;
    mightBeSpam: boolean;
    priority: 'high' | 'normal' | 'low';
    variables: Record<string, any>;
    private envelopeFrom;
    private messageId;
    private static emailValidator;
    constructor(options: IEmailOptions);
    /**
     * Validates an email address using smartmail's EmailAddressValidator
     * For constructor validation, we only check syntax to avoid delays
     * Supports RFC-compliant addresses including display names and bounce addresses.
     *
     * @param email The email address to validate
     * @returns boolean indicating if the email is valid
     */
    private isValidEmail;
    /**
     * Extracts the email address from a string that may contain a display name.
     * Handles formats like:
     * - simple@example.com
     * - "John Doe" <john@example.com>
     * - John Doe <john@example.com>
     *
     * @param emailString The email string to parse
     * @returns The extracted email address or null
     */
    private extractEmailAddress;
    /**
     * Parses and validates recipient email addresses
     * @param recipients A string or array of recipient emails
     * @returns Array of validated email addresses
     */
    private parseRecipients;
    /**
     * Basic sanitization for strings to prevent header injection
     * @param input The string to sanitize
     * @returns Sanitized string
     */
    private sanitizeString;
    /**
     * Gets the domain part of the from email address
     * @returns The domain part of the from email or null if invalid
     */
    getFromDomain(): string | null;
    /**
     * Gets the clean from email address without display name
     * @returns The email address without display name
     */
    getFromAddress(): string;
    /**
     * Converts IDN (International Domain Names) to ASCII
     * @param email The email address to convert
     * @returns The email with ASCII-converted domain
     */
    private convertIDNToASCII;
    /**
     * Gets clean to email addresses without display names
     * @returns Array of email addresses without display names
     */
    getToAddresses(): string[];
    /**
     * Gets clean cc email addresses without display names
     * @returns Array of email addresses without display names
     */
    getCcAddresses(): string[];
    /**
     * Gets clean bcc email addresses without display names
     * @returns Array of email addresses without display names
     */
    getBccAddresses(): string[];
    /**
     * Gets all recipients (to, cc, bcc) as a unique array
     * @returns Array of all unique recipient email addresses
     */
    getAllRecipients(): string[];
    /**
     * Gets primary recipient (first in the to field)
     * @returns The primary recipient email or null if none exists
     */
    getPrimaryRecipient(): string | null;
    /**
     * Checks if the email has attachments
     * @returns Boolean indicating if the email has attachments
     */
    hasAttachments(): boolean;
    /**
     * Add a recipient to the email
     * @param email The recipient email address
     * @param type The recipient type (to, cc, bcc)
     * @returns This instance for method chaining
     */
    addRecipient(email: string, type?: 'to' | 'cc' | 'bcc'): this;
    /**
     * Add an attachment to the email
     * @param attachment The attachment to add
     * @returns This instance for method chaining
     */
    addAttachment(attachment: IAttachment): this;
    /**
     * Add a custom header to the email
     * @param name The header name
     * @param value The header value
     * @returns This instance for method chaining
     */
    addHeader(name: string, value: string): this;
    /**
     * Set the email priority
     * @param priority The priority level
     * @returns This instance for method chaining
     */
    setPriority(priority: 'high' | 'normal' | 'low'): this;
    /**
     * Set a template variable
     * @param key The variable key
     * @param value The variable value
     * @returns This instance for method chaining
     */
    setVariable(key: string, value: any): this;
    /**
     * Set multiple template variables at once
     * @param variables The variables object
     * @returns This instance for method chaining
     */
    setVariables(variables: Record<string, any>): this;
    /**
     * Get the subject with variables applied
     * @param variables Optional additional variables to apply
     * @returns The processed subject
     */
    getSubjectWithVariables(variables?: Record<string, any>): string;
    /**
     * Get the text content with variables applied
     * @param variables Optional additional variables to apply
     * @returns The processed text content
     */
    getTextWithVariables(variables?: Record<string, any>): string;
    /**
     * Get the HTML content with variables applied
     * @param variables Optional additional variables to apply
     * @returns The processed HTML content or undefined if none
     */
    getHtmlWithVariables(variables?: Record<string, any>): string | undefined;
    /**
     * Apply template variables to a string
     * @param template The template string
     * @param additionalVariables Optional additional variables to apply
     * @returns The processed string
     */
    private applyVariables;
    /**
     * Gets the total size of all attachments in bytes
     * @returns Total size of all attachments in bytes
     */
    getAttachmentsSize(): number;
    /**
     * Perform advanced validation on sender and recipient email addresses
     * This should be called separately after instantiation when ready to check MX records
     * @param options Validation options
     * @returns Promise resolving to validation results for all addresses
     */
    validateAddresses(options?: {
        checkMx?: boolean;
        checkDisposable?: boolean;
        checkSenderOnly?: boolean;
        checkFirstRecipientOnly?: boolean;
    }): Promise<{
        sender: {
            email: string;
            result: any;
        };
        recipients: Array<{
            email: string;
            result: any;
        }>;
        isValid: boolean;
    }>;
    /**
     * Convert this email to a smartmail instance
     * @returns A new Smartmail instance
     */
    toSmartmail(): Promise<plugins.smartmail.Smartmail<any>>;
    /**
     * Get the from email address
     * @returns The from email address
     */
    getFromEmail(): string;
    /**
     * Get the subject (Smartmail compatibility method)
     * @returns The email subject
     */
    getSubject(): string;
    /**
     * Get the body content (Smartmail compatibility method)
     * @param isHtml Whether to return HTML content if available
     * @returns The email body (HTML if requested and available, otherwise plain text)
     */
    getBody(isHtml?: boolean): string;
    /**
     * Get the from address (Smartmail compatibility method)
     * @returns The sender email address
     */
    getFrom(): string;
    /**
     * Get the message ID
     * @returns The message ID
     */
    getMessageId(): string;
    /**
     * Convert the Email instance back to IEmailOptions format.
     * Useful for serialization or passing to APIs that expect IEmailOptions.
     * Note: This loses some Email-specific properties like messageId and envelopeFrom.
     *
     * @returns IEmailOptions representation of this email
     */
    toEmailOptions(): IEmailOptions;
    /**
     * Set a custom message ID
     * @param id The message ID to set
     * @returns This instance for method chaining
     */
    setMessageId(id: string): this;
    /**
     * Get the envelope from address (return-path)
     * @returns The envelope from address
     */
    getEnvelopeFrom(): string;
    /**
     * Set the envelope from address (return-path)
     * @param address The envelope from address to set
     * @returns This instance for method chaining
     */
    setEnvelopeFrom(address: string): this;
    /**
     * Creates an RFC822 compliant email string
     * @param variables Optional template variables to apply
     * @returns The email formatted as an RFC822 compliant string
     */
    toRFC822String(variables?: Record<string, any>): string;
    /**
     * Convert to simple Smartmail-compatible object (for backward compatibility)
     * @returns A Promise with a simple Smartmail-compatible object
     */
    toSmartmailBasic(): Promise<any>;
    /**
     * Create an Email instance from a Smartmail object
     * @param smartmail The Smartmail instance to convert
     * @returns A new Email instance
     */
    static fromSmartmail(smartmail: plugins.smartmail.Smartmail<any>): Email;
}