Maaz Zindani

Loading the index…

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

PHPMailer fails at the password step with Gmail SMTP

ErrorSMTP ERROR: Password command failed

Short answer

Google stopped accepting a normal account password for SMTP in 2022. PHPMailer logs Password command failed when Google refuses the login. Turn on 2-Step Verification, create an app password and use it as Password, or move to XOAUTH2. Use port 587 with STARTTLS and turn on SMTPDebug to read the server's reply.

  • Applies to PHPMailer 6.9, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Turn on the SMTP transcript at level 2. The line Google sends after the password step explains the refusal.

    $mail->SMTPDebug = SMTP::DEBUG_SERVER; // level 2
    $mail->Debugoutput = 'error_log';
  2. 2Match what you see, then jump to its fix

    1. 1Password command failed right after AUTH LOGIN, with a real Google account password in PasswordThe account's normal password is used for SMTPFix
    2. 2The app passwords page is missing in the Google Account2-Step Verification is off, so no app password can existFix
    3. 3SMTP worked for weeks, then Password command failed on its ownThe app password was revokedFix

What does the error look like?

  • SMTP ERROR: Password command failed
  • SMTP ERROR: Password command failed:

Cause 1 of 3

The account's normal password is used for SMTP

1Check

The PHPMailer troubleshooting guide says Google suspended password-based logins on 30 May 2022. Since then a script must use an app password or XOAUTH2.

grep -n "Password" mail-config.php

2Fix

Create an app password for the account and put it in Password. Keep it in an environment variable, not in the repository.

$mail->isSMTP();
$mail->Host       = 'smtp.gmail.com';
$mail->SMTPAuth   = true;
$mail->Username   = getenv('SMTP_USER');
$mail->Password   = getenv('SMTP_APP_PASSWORD');
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->Port       = 587;

3Verify

Send a test message and read the end of the debug transcript.

php send-test.php

Confirmed by github.com

Did this fix it?

Cause 2 of 3

2-Step Verification is off, so no app password can exist

1Check

Google's help page says an app password needs 2-Step Verification on the account. It may also be unavailable if only security keys are used for 2-Step, the account is a work or school account, or Advanced Protection is on.

# open myaccount.google.com/apppasswords while signed in to the sending account

2Fix

Turn on 2-Step Verification, then create the app password. On a work or school account, ask the Google Workspace admin for a supported sending method or use XOAUTH2.

# Google Account > Security > 2-Step Verification, then App passwords

3Verify

The app passwords page opens and gives a 16-digit passcode; use it in the config above and send a test message.

php send-test.php

Confirmed by support.google.com

Did this fix it?

Cause 3 of 3

The app password was revoked

1Check

Google's help page says changing the Google Account password revokes existing app passwords.

# compare the date of the last account password change with the date the mail stopped

2Fix

Create a new app password, update the value your application reads, and restart PHP-FPM or the queue worker so it picks up the change.

export SMTP_APP_PASSWORD='new-app-password'
sudo systemctl restart php8.3-fpm

3Verify

Send a test message after the restart.

php send-test.php

Confirmed by support.google.com

Did this fix it?

How do I stop it coming back?

  • Keep SMTP credentials in environment variables or a secrets store, never in the code.
  • Use SMTPSecure STARTTLS with port 587, as the PHPMailer guide recommends, so the login never crosses an unencrypted link.
  • Write the app-password creation date next to the secret, so a revoked one is easy to spot.
  • Consider XOAUTH2 or a transactional mail provider for production mail.

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

Apache returns 403 when a URL contains %3F

a request like /page%3Fname=test is refused while /page?name=test works

Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.

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