Custom SMTP Email Integration with Novu

Send transactional email through your own SMTP server. Novu opens the connection with the same settings Nodemailer uses, and the fields on the integration form map directly to those settings.

Create the integration

Add the Custom SMTP provider

Open the Integrations page, select Add a provider, then select Custom SMTP.

Fill in the server and the sender

Host, Port, From email address, and Sender name are required. Set User and Password when the server requires authentication. Pick the TLS toggles for your port as described in TLS settings.

Activate the integration

Switch the integration from Disabled to Active, then select Update.

Configuration fields

Field	Required	What to enter
User	No	SMTP username.
Password	No	SMTP password or the app password your provider issued for SMTP.
Host	Yes	Hostname of the SMTP server, with no `smtp://` prefix, port, or path.
Port	Yes	TCP port, an integer from 1 to 65535.
Secure	No	Use implicit TLS.
Require TLS	No	Fail the send if the server does not offer STARTTLS.
Ignore TLS	No	Skip STARTTLS and send on a plain connection.
TLS options	No	The only JSON field. Paste one JSON object of extra Node.js TLS settings. Every other field on this form is plain text.
DKIM: Domain name	No	Domain placed in the DKIM signature (`d=`).
DKIM: Private key	No	PEM private key, including the `-----BEGIN` and `-----END` lines.
DKIM: Key selector	No	Selector placed in the DKIM signature (`s=`).
From email address	Yes	Address recipients see in From. The SMTP account must be allowed to send as this address.
Sender name	Yes	Display name shown next to the From address, such as `Acme`.

Novu authenticates only when both User and Password have a value. Novu waits 10 seconds to open the TCP connection and 10 seconds on the socket after that.

TLS settings

Secure selects the connection mode, and the other TLS controls depend on it.

Port	Secure	Require TLS	Ignore TLS	TLS options
`465`	On	Ignored	Ignored	Applied
`587` or `25`	Off	Optional	Optional	Ignored

With Secure on, the connection is encrypted before the first SMTP command. With Secure off, Novu opens a plain connection and upgrades with STARTTLS when the server advertises it. Require TLS fails the send if that upgrade does not happen. Ignore TLS skips the upgrade, and it wins if both toggles are on. TLS options is a text area. Paste one JSON object into it. Novu rejects a string, an array, or invalid JSON, and ignores the field while Secure is off.

{
  "minVersion": "TLSv1.2"
}

To trust a private certificate authority, turn Secure on and set ca to that authority’s PEM certificate. ca replaces the default public authorities for this connection, so the server certificate must chain to the authority you supply. Keep line breaks in the PEM as \n inside the JSON string.

{
  "ca": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----\n"
}

Keep certificate checks enabled. {"rejectUnauthorized":false} turns them off, so a host on the connection path can impersonate the mail server and receive the SMTP credentials. Novu checks the server certificate against Host. A servername key in TLS options is replaced with Host. If a send fails with Host: ... is not in the cert's altnames: DNS:..., set Host to one of the DNS: names in that error or to a name covered by a listed wildcard. An internal alias, a different domain, or an IP address fails this check even when it reaches the same server. Enter Host without the trailing dot Node prints in the error.

DKIM

Novu signs the message only when all three DKIM fields are set. Publish the matching public key at {selector}._domainkey.{domain}. For domain example.com and selector novu, that name is novu._domainkey.example.com.

Troubleshooting

Symptom	Action
Authentication failed	Set both User and Password, and confirm the account may send as From email address.
Connection timed out	Confirm Host and Port, and allow SMTP from the public internet. Novu Cloud workers do not use a fixed IP address.
`Requests to private or reserved IP addresses are not allowed`	Set Host to a hostname that resolves to the private address, and add that hostname or address to `NOVU_SAFE_OUTBOUND_ALLOW` on the API and worker. `localhost` cannot be allow-listed. A literal private IP such as `10.0.0.1` is also rejected in Host. See Deploy Novu with Docker.
TLS handshake failed on `587` or `25`	Turn Secure off. Those ports use STARTTLS.
`is not in the cert's altnames`	Set Host to a name on the certificate, as described in TLS settings.

Next steps

Configure bcc, cc, and reply-to

Learn how to configure bcc, cc, and reply-to for your email notifications using email overrides

Sending email attachments

Learn how to send attachments with email notifications

Use different email integration

Learn how to use different email provider integrations to be used to send emails

Getting Started

Integrate <Inbox />

Integrate <Subscription />

Build a Workflow

Integrate Channels Providers

SDKs

Developer

Account

Build with AI

Additional Resources

Custom SMTP Email Integration with Novu

Create the integration

Add the Custom SMTP provider

Fill in the server and the sender

Activate the integration

Configuration fields

TLS settings

DKIM

Troubleshooting

Next steps

Configure bcc, cc, and reply-to

Sending email attachments

Use different email integration

​Create the integration

​Add the Custom SMTP provider

​Fill in the server and the sender

​Activate the integration

​Configuration fields

​TLS settings

​DKIM

​Troubleshooting

​Next steps

Configure bcc, cc, and reply-to

Sending email attachments

Use different email integration

Create the integration

Add the Custom SMTP provider

Fill in the server and the sender

Activate the integration

Configuration fields

TLS settings

DKIM

Troubleshooting

Next steps