Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Nodemailer fails to send mail: connection timeout, TLS or login errors

Errorerr.code is ETIMEDOUT, ETLS, EAUTH or ESOCKET

Short answer

Read err.code first: Nodemailer sets it for every failure. ETIMEDOUT with a timeoutType says which stage stalled, ETLS means the TLS settings do not match the port, EAUTH means the server refused the login. Use secure true only on port 465, and leave it false on 587.

  • Applies to Nodemailer (current), Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Turn on the SMTP log and print the error code and the stage. The code tells you which cause below applies.

    const transporter = nodemailer.createTransport({ host, port, secure, auth, logger: true })
    transporter.sendMail(msg).catch((e) => console.error(e.code, e.timeoutType, e.message))
  2. 2Match what you see, then jump to its fix

    1. 1ETIMEDOUT at the greeting stage, or ETLS right after connecting.secure does not match the portFix
    2. 2err.code is EAUTH (or ENOAUTH when credentials are missing).The server rejects the loginFix
    3. 3ETIMEDOUT with timeoutType connect, EDNS, or ESOCKET such as a connection reset.The connection cannot be opened from this networkFix

What does the error look like?

  • err.code is ETIMEDOUT, ETLS, EAUTH or ESOCKET
  • ETIMEDOUT with timeoutType connect, greeting, upgrade or socket

Cause 1 of 3

secure does not match the port

1Check

Nodemailer documents that secure true is for port 465, where TLS starts at once. For 587 or 25 it must stay false so STARTTLS upgrades the connection. false does not mean unencrypted.

grep -n "secure\|port" mailer.js

2Fix

Pair the port with the right flag, and require the upgrade on 587 if you want sending to fail rather than go unencrypted.

// port 587, STARTTLS
nodemailer.createTransport({ host: 'smtp.example.com', port: 587, secure: false, requireTLS: true, auth })
// port 465, TLS from the start
nodemailer.createTransport({ host: 'smtp.example.com', port: 465, secure: true, auth })

3Verify

Send a test message and watch the log pass the greeting.

node send-test.js

Confirmed by nodemailer.com

Did this fix it?

Cause 2 of 3

The server rejects the login

1Check

EAUTH means the server rejected the credentials or the authentication method. ENOAUTH means the server asked for credentials and none were given.

node -e "console.log(!!process.env.SMTP_USER, !!process.env.SMTP_PASS)"

2Fix

Pass user and pass in the auth object from the right environment variables. Use the account or app password your provider issues for SMTP.

auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS }

3Verify

The log shows authentication succeeded and the message is accepted.

node send-test.js

Confirmed by nodemailer.com

Did this fix it?

Cause 3 of 3

The connection cannot be opened from this network

1Check

ETIMEDOUT carries a timeoutType (connect, greeting, upgrade or socket). EDNS means the hostname was not resolved. The default connectionTimeout is 120000 ms and greetingTimeout 30000 ms.

nc -vz smtp.example.com 587

2Fix

Fix the hostname, or ask your host whether outbound SMTP on that port is allowed. Switch to the other documented port if one is blocked.

nodemailer.createTransport({ host: 'smtp.example.com', port: 465, secure: true, connectionTimeout: 20000, auth })

3Verify

nc succeeds and a test message is sent.

nc -vz smtp.example.com 465

Confirmed by nodemailer.com

Did this fix it?

How do I stop it coming back?

  • Log err.code and err.timeoutType on every failed send, not only err.message.
  • Keep SMTP host, port, secure flag and credentials together in one config block.
  • Use the transactionLog option in production, as it records SMTP commands without the message content.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Strapi admin blocks uploaded images and media because of its CSP

Refused to load media from 'https://bucket.s3.eu-west-1.amazonaws.com/...' because it violates the following Content Security Policy directive: "media-src 'self' data: blob:".

Strapi's default strapi::security middleware limits images and media to 'self'.

2 causes, each with a fix

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.