292 lines
9.5 KiB
TypeScript
292 lines
9.5 KiB
TypeScript
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;
|
|
}
|