Go to websiteGet a demo

Email

The Email class provides a robust interface for sending emails using the SMTP protocol. It simplifies the process of configuring a mail transport, defining message options, and sending emails with various types of content and attachments.

Heisenware ships with a pre-initialized email instance, which you can directly use without calling create. The instance is called internal-email and is always available:

In case you want to connect to another mailing system, you have to create an instance first and configure it with the connection and authentication details for your specific email server (e.g., Gmail, Office 365, or a private SMTP server).

create

Creates a new email client instance by configuring and establishing a connection (or connection pool) to an SMTP server.

Parameters

  • options: An object defining the server connection details.

    • host: The hostname or IP address of your SMTP server (e.g., smtp.gmail.com).

    • port: The port to connect to. Common values are:

      • 465: For SMTPS (SMTP over SSL/TLS). Use with secure: true.

      • 587: For SMTP with STARTTLS (the connection starts insecurely and is upgraded to TLS). Use with secure: false.

      • 25: The default SMTP port, often used for unencrypted connections.

    • secure: A boolean. If true, the connection uses direct SSL/TLS. If false (the default), it attempts to upgrade the connection using STARTTLS if the server supports it.

  • auth: An object containing the authentication credentials.

    • user: The username, which is typically your full email address.

    • pass: The password for the email account.

  • defaults: An optional object to specify default values for all emails sent with this instance. This is very useful for setting a consistent from address.

Example 1: Connecting to a standard SMTP server with STARTTLS (e.g., Office 365)

Example 2: Connecting to a server requiring direct SSL/TLS (e.g., older configurations)

send

Composes and sends an email. This function automatically detects if the content is HTML or plain text.

Parameters

  • address: An object defining the email recipients.

    • from: The sender's email address. Can be a simple address ('[email protected]') or a formatted string ('"Sender Name" <[email protected]>').

    • to: The primary recipient(s). Can be a single email string, a comma-separated string of emails, or an array of strings.

    • cc: Carbon copy recipient(s).

    • bcc: Blind carbon copy recipient(s).

  • subject: The subject line of the email.

  • content: The body of the email. Can be a plain text string or an HTML string.

  • attachments: An optional array of attachment objects.

Attachment Object Properties

Each object in the attachments array can have the following properties:

  • filename: The name of the file as it will appear in the email.

  • content: The content of the attachment, typically as a base64 encoded string.

  • path: The local file path to the attachment. This is more memory-efficient for large files as it streams the file from disk.

  • href: A URL to the file. Nodemailer will download the content from the URL.

  • cid: A unique Content-ID string. This is used to embed the attachment as an inline image within the HTML body (e.g., <img src="cid:my-image-cid">).

Output

Returns true on a successful send.

Examples

Example 1: Sending a simple plain text email

Example 2: Sending an HTML email

Example 3: Sending an email with an attachment from a file path

Example 4: Sending an email with an attachment from a base64 string

Example 5: Sending an HTML email with an inline image

App Builder Example

In the example below, the subject, content and attachments are dynamically filled from a Form and a File Upload, while the recipients address is predefined. A button triggers the send function.

This is how the email looks like:

Demo video

Last updated