Email

The email connector sends emails via SMTP by configuring a mail transport once and transmitting messages containing plain text or HTML content alongside any number of attachments.

This connector requires instance creation before you can interact with an SMTP server, though Heisenware includes a pre-initialized instance out of the box.

Ready-to-use instance

Heisenware ships with a pre-initialized email instance called internal-email. It is always available, letting you call send directly.

To send through another mailing system (such as Gmail, Office 365, or a private SMTP server), create a new instance with your server's connection and authentication details.

create

Creates a new email client instance by configuring the connection to an SMTP server.

Parameters

Input	Key	Description	Type
options	host	The hostname or IP address of your SMTP server (such as smtp.gmail.com).	string
	port	The port to connect to. Common values include 465 for SMTPS (use with secure: true), 587 for STARTTLS (use with secure: false), or 25 for unencrypted SMTP. Default 587, or 465 if secure is true.	integer
	secure	If true, the connection uses direct SSL/TLS. If false, the connection upgrades to TLS via STARTTLS if the server supports it. Default false.	boolean
	ignoreTLS	If true (and secure is false), the connector does not use TLS even if the server supports STARTTLS. Default false.	boolean
	requireTLS	If true (and secure is false), the connection must upgrade to STARTTLS, otherwise the connector does not send the message. Default false.	boolean
auth	user	The username, typically your full email address.	string
	pass	The password for the email account.	string
	type	The authentication type: login or oauth2. Default login.	string
defaults		An object merged into every email sent with this instance, such as to set a shared from address.	object

For OAuth2 (type: oauth2), provide the standard nodemailer OAuth2 keys in auth (such as clientId, clientSecret, refreshToken, and accessToken).

Right-click the auth input and mark it as a secret to mask the password.

Examples

Example 1: Connecting with STARTTLS (such as Office 365)

# options
host: smtp.office365.com
port: 587
secure: false
# auth
user: [e-mail]
pass: my-secret-password
# defaults
from: '"My Application" <[e-mail]>'

Example 2: Connecting with direct SSL/TLS

# options
host: mail.my-legacy-server.com
port: 465
secure: true
# auth
user: [e-mail]
pass: another-password

Output

Returns the name of the created instance.

send

Composes and sends an email. The function automatically detects whether content is HTML or plain text.

Parameters

Input	Key	Description	Type
address	from	The sender's address, plain ([e-mail]) or formatted ('"Sender Name" <[e-mail]>'). Omit this if the instance defines a default from.	string
	to	The primary recipient or recipients, provided as a single address, a comma-separated string, or an array of strings.	string or array
	cc	Carbon copy recipients, using the same formats as to.	string or array
	bcc	Blind carbon copy recipients, using the same formats as to.	string or array
subject		The subject line of the email.	string
content		The body of the email, provided as plain text or HTML.	string
attachments	filename	The filename shown in the email. Unicode characters are allowed.	string
	content	The attachment content as a string, Buffer, or stream. For base64 content, add encoding: base64.	any
	encoding	The encoding of the content value, such as base64.	string
	path	A file path to the attachment. This streams the file from disk, which is more memory-efficient for large files than content.	string
	href	A URL to the file. The connector downloads the content from this URL.	string
	httpHeaders	Optional HTTP headers to pass with the href request, such as an authorization header.	object
	cid	A unique content ID to embed the attachment as an inline image in the HTML body (for example, <img src="cid:my-image-cid">).	string

The attachments property accepts an array of objects containing the keys listed above. Provide either content, path, or href per attachment.

Examples

Example 1: Plain text email

# address
to: '[e-mail]'
from: '"Support Team" <[e-mail]>'
# subject
Your recent support ticket
# content
Hello,

This is a confirmation that we have received your support ticket. We will get back to you shortly.

Regards,
The Support Team

Example 2: HTML email

# address
to: '[e-mail]'
from: '"Sales" <[e-mail]>'
# subject
Your weekly newsletter
# content
'<h1>Our Top Story This Week</h1><p>Check out our latest product, now available for pre-order!</p><a href="https://my-company.com/products/new">Pre-order Now</a>'

Example 3: Attachment from a file path

# address
to: '[e-mail]'
from: '[e-mail]'
# subject
Q3 financial report
# content
Please find the Q3 financial report attached.
# attachments
[
  {
    filename: 'Q3-Report.pdf',
    path: '/path/to/local/reports/q3_financials.pdf'
  }
]

Example 4: Attachment from a base64 string

# address
to: '[e-mail]'
from: '[e-mail]'
# subject
Your invoice #12345
# content
Your invoice is attached.
# attachments
[
  {
    filename: 'invoice.pdf',
    content: 'JVBERi0xLjQKJ...', # the base64 string
    encoding: 'base64'
  }
]

Example 5: HTML email with an inline image

# address
to: '[e-mail]'
from: '[e-mail]'
# subject
Check out our new logo!
# content
'<p>We are excited to unveil our new company logo:</p><img src="cid:[e-mail]">'
# attachments
[
  {
    filename: 'logo.png',
    path: '/path/to/assets/new_logo.png',
    cid: '[e-mail]' # this cid must match the src in the HTML
  }
]

Output

Returns true on a successful send. If the send fails, the function logs the error and returns nothing without throwing an error. The same applies when the instance was created with a failing configuration: the connector then skips sending and logs a warning.

delete

Removes the instance and its configured mail transport.

Irreversible action

Deleting an instance removes its configuration. To send through that server again, you must trigger create anew.

Parameters

None.

Output

Returns true upon removal.

App Builder example

In the example below, a form fills the subject and content, an upload widget provides the attachments, and the recipient address is predefined. A button triggers the send function.

This is how the email looks:

Video demo