Fix Net::SMTPAuthenticationError: 535 5.7.8 Authentication credentials invalid in Rails

This error means Rails cannot authenticate with your SMTP server using the provided credentials. The username or password is incorrect, or the SMTP server requires an app-specific password or OAuth2 token. Verify your SMTP settings in config/environments and use Rails credentials to store sensitive values securely.

Reading the Stack Trace

Here's what each line means:

• net/smtp.rb:995:in `check_auth_response': Ruby's Net::SMTP library received a 535 authentication failure from the mail server.
• mail (2.8.1) lib/mail/network/delivery_methods/smtp.rb:112:in `deliver!': The Mail gem is attempting to deliver the email via SMTP when authentication fails.
• app/controllers/users_controller.rb:22:in `create': The user creation action triggers a welcome email that fails to send.

Common Causes

# config/environments/production.rb
config.action_mailer.smtp_settings = {
  address: 'smtp.gmail.com',
  port: 587,
  user_name: 'myapp@gmail.com',
  password: 'old_password',  # Expired or wrong password
  authentication: 'plain'
}

config.action_mailer.smtp_settings = {
  address: 'smtp.gmail.com',
  port: 587,
  user_name: 'myapp@gmail.com',
  password: 'regular_gmail_password',  # Need app password with 2FA
  authentication: 'plain'
}

# config/environments/production.rb
config.action_mailer.smtp_settings = {
  password: 'plaintext_password'  # Insecure and prone to rotation issues
}

The Fix

Store SMTP credentials in Rails encrypted credentials instead of hardcoding them. Use rails credentials:edit to set smtp.user_name and smtp.password. Generate an app-specific password if using Gmail with 2FA.

config.action_mailer.smtp_settings = {
  address: 'smtp.gmail.com',
  port: 587,
  user_name: 'myapp@gmail.com',
  password: 'old_password',
  authentication: 'plain'
}

config.action_mailer.smtp_settings = {
  address: 'smtp.gmail.com',
  port: 587,
  user_name: Rails.application.credentials.dig(:smtp, :user_name),
  password: Rails.application.credentials.dig(:smtp, :password),
  authentication: 'plain',
  enable_starttls_auto: true
}

Testing the Fix

require 'rails_helper'

RSpec.describe UserMailer, type: :mailer do
  describe '#welcome_email' do
    let(:user) { create(:user, email: 'test@example.com') }
    let(:mail) { UserMailer.welcome_email(user) }

    it 'renders the headers' do
      expect(mail.subject).to eq('Welcome to MyApp')
      expect(mail.to).to eq(['test@example.com'])
    end

    it 'renders the body' do
      expect(mail.body.encoded).to include('Welcome')
    end

    it 'enqueues the email' do
      expect { mail.deliver_later }.to have_enqueued_job(ActionMailer::MailDeliveryJob)
    end
  end
end

Run your tests:

bundle exec rspec spec/mailers/user_mailer_spec.rb

Pushing Through CI/CD

git checkout -b fix/rails-mailer-smtp-auth,git add config/environments/production.rb,git commit -m "fix: use Rails credentials for SMTP authentication",git push origin fix/rails-mailer-smtp-auth

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
        ports: ['5432:5432']
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true
      - run: bin/rails db:setup
      - run: bundle exec rspec

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

gem install bugstack

require 'bugstack'

Bugstack.init(api_key: ENV['BUGSTACK_API_KEY'])

Deploying the Fix (Manual Path)

1. Update SMTP credentials in Rails encrypted credentials.
2. Verify credentials with rails runner to test SMTP connection.
3. Run mailer specs.
4. Open a pull request.
5. Merge and verify emails send correctly from staging.

Frequently Asked Questions