Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Email delivery

Sending mail from Java fails with 530 5.7.0 Must issue a STARTTLS command first

ErrorSMTPSendFailedException: 530 5.7.0 Must issue a STARTTLS command first

Short answer

The server will not take your login or message until the connection is encrypted, and your session never asked for TLS. Set mail.smtp.starttls.enable to true, add starttls.required so a missing upgrade fails loudly, and keep mail.smtp.auth on with real credentials. Use port 587 for STARTTLS.

  • Applies to Jakarta Mail 2.x, Angus Mail 2.0, JDK 17, JDK 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Turn on the protocol trace and look for the server's capability list after EHLO. If STARTTLS is offered and your client never sent it, the property is missing.

    session.setDebug(true);
    // or: java -Dmail.debug=true MyApp
  2. 2Match what you see, then jump to its fix

    1. 1The trace shows EHLO, a STARTTLS capability from the server, and then MAIL FROM or AUTH going out without a STARTTLS command in between.mail.smtp.starttls.enable is not setFix
    2. 2It works on some servers and fails on others, or the connection silently continues without encryption.STARTTLS is optional in your config, so a failed upgrade goes unnoticedFix
    3. 3After STARTTLS is fixed, the next error is 530 5.7.0 Authentication Required, or the send is refused after MAIL FROM.The server also needs authentication, which is off by defaultFix

What does the error look like?

  • SMTPSendFailedException: 530 5.7.0 Must issue a STARTTLS command first
  • 530 5.7.0 Must issue a STARTTLS command first

Cause 1 of 3

mail.smtp.starttls.enable is not set

1Check

mail.smtp.starttls.enable defaults to false. When it is true, the client uses STARTTLS, if the server supports it, before issuing any login commands.

grep -rn "starttls" src/ application.properties 2>/dev/null

2Fix

Enable STARTTLS and use the submission port. The FAQ gives exactly this fix for this error.

props.put("mail.smtp.host", "smtp.example.com");
props.put("mail.smtp.port", "587");
props.put("mail.smtp.starttls.enable", "true");

3Verify

The trace now shows STARTTLS and a TLS start before the login commands.

java -Dmail.debug=true MyApp

Confirmed by eclipse-ee4j.github.io

Did this fix it?

Cause 2 of 3

STARTTLS is optional in your config, so a failed upgrade goes unnoticed

1Check

With only starttls.enable, the connection continues without TLS if the server does not offer STARTTLS. starttls.required makes connect fail instead.

grep -rn "starttls.required" src/ application.properties 2>/dev/null

2Fix

Require STARTTLS, so the error you see is about the real problem and mail never goes out in clear text.

props.put("mail.smtp.starttls.enable", "true");
props.put("mail.smtp.starttls.required", "true");

3Verify

If the server cannot upgrade, connect now throws at once, with the reason in the trace.

java -Dmail.debug=true MyApp

Confirmed by eclipse-ee4j.github.io

Did this fix it?

Cause 3 of 3

The server also needs authentication, which is off by default

1Check

mail.smtp.auth defaults to false. The FAQ notes that a server which demands STARTTLS will likely require authentication too.

grep -rn "smtp.auth" src/ application.properties 2>/dev/null

2Fix

Turn authentication on and send with credentials. For Gmail, Google asks for an app password or OAuth for the account.

props.put("mail.smtp.auth", "true");
Transport.send(message, username, password);

3Verify

The trace shows AUTH succeed and the message accepted.

java -Dmail.debug=true MyApp

Confirmed by eclipse-ee4j.github.io

Did this fix it?

How do I stop it coming back?

  • Keep one tested set of SMTP properties per provider in config, with the port, STARTTLS and auth together.
  • Set starttls.required in production so a failed upgrade is an error, not a clear-text send.
  • Do not hard-code the password; read it from the environment or a secret store.

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?

Related fixes

Email

Django send_mail fails or hangs with an SSL error

smtplib.SMTPException raised from send_mail()

Django has two secure modes that must not be mixed: EMAIL_USE_TLS for explicit TLS (STARTTLS, usually port 587) and EMAIL_USE_SSL for implicit TLS (usually port 465).

4 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.