Google SMTP Configuration for ColibriPlus

This guide will walk you through the process of obtaining Google SMTP credentials and configuring them for use with ColibriPlus. Google SMTP allows your ColibriPlus application to send emails through Gmail's secure mail servers.

Why use Google SMTP? It's much preffed to use your own SMTP on your own domain, but if you don't have one, you can use Google SMTP. Since setting up your own SMTP server is not a trivial task and sometimes it's much easier to use Google SMTP.

Prerequisites

Before you begin, ensure you have:

• A Google account (Gmail)
• Access to your ColibriPlus application's .env file

Why Google SMTP?

Google's SMTP service provides several advantages:

• Reliability: Gmail's infrastructure ensures high deliverability rates
• Security: Built-in encryption and spam protection
• Familiarity: Easy to manage through your existing Google account
• Free tier: Suitable for small to medium-sized applications

2FA Setup

Google requires 2FA to be enabled before you can generate App Passwords, which are necessary for SMTP authentication.

1. Go to your Google Account Security page
2. Under "How you sign in to Google," locate 2-Step Verification
3. Click on 2-Step Verification and follow the prompts to set it up
4. Choose your preferred verification method (phone number, authenticator app, etc.)
5. Complete the setup process and verify that 2FA is now enabled

Note: If you already have 2FA enabled, you can skip this step.

Obtain Password

App Passwords are 16-character codes that allow apps to access your Google account securely without using your actual password.

1. Visit the App Passwords page
   • Alternatively, go to Google Account → Security → 2-Step Verification → App Passwords
2. You may be asked to sign in again for security verification
3. Under "Select app," choose Mail from the dropdown
4. Under "Select device," choose Other (Custom name)
5. Enter a descriptive name like "ColibriPlus Laravel App"
6. Click Generate
7. Google will display a 16-character password in a yellow box
8. Important: Copy this password immediately as you won't be able to see it again

Edit .env file

Now that you have your App Password, edit your .env file and update the following email configuration variables:

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-16-character-app-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your-email@gmail.com
MAIL_FROM_NAME="Your Site Name"

Clear Cache

After updating your .env file, clear ColibriPlus's configuration cache to ensure the changes take effect:

php colibri config:clear
php colibri cache:clear

Test SMTP

Verify that your SMTP configuration works correctly by sending a test email:

php colibri mail:check

Enter the email address you want to send test email to and hit enter.

If you do not see any errors, then your SMTP configuration is working correctly.

Troubleshooting

"Username and Password not accepted" Error

• Double-check that you copied the App Password correctly (no spaces)
• Ensure 2FA is enabled on your Google account
• Verify that you're using the correct Gmail address
• Try generating a new App Password

"Could not authenticate" Error

• Confirm MAIL_PORT is set to 587
• Verify MAIL_ENCRYPTION is set to tls
• Check that your server allows outbound connections on port 587

Emails Going to Spam

• Configure proper SPF and DKIM records for your domain
• Ensure your MAIL_FROM_ADDRESS matches your authenticated Gmail address
• Keep your email content professional and avoid spam trigger words

Daily Sending Limits

Google imposes sending limits on Gmail accounts:

• Free Gmail accounts: 500 emails per day
• Google Workspace accounts: 2,000 emails per day

If you exceed these limits, consider using a dedicated email service provider like SendGrid or Amazon SES.

Security Best Practices

1. Never commit your App Password to version control: Keep your .env file in .gitignore
2. Use environment-specific credentials: Different App Passwords for development, staging, and production
3. Rotate passwords regularly: Generate new App Passwords periodically
4. Revoke unused App Passwords: Remove old App Passwords from your Google Account settings
5. Monitor your account: Regularly check your Google account's security activity

Alternative: Google Workspace

If you're using Google Workspace (formerly G Suite), the process is similar but you may have additional options:

• You can use your domain email address instead of @gmail.com
• Higher sending limits (2,000 emails per day)
• Additional administrative controls

The same App Password process applies for Google Workspace accounts.

Conclusion

You've successfully configured Google SMTP credentials for ColibriPlus! Your ColibriPlus application can now send emails reliably through Gmail's servers. Remember to monitor your sending volume and keep your credentials secure.

For more information about ColibriPlus's mail configuration, visit the official ColibriPlus Mail documentation.