orange-soft / laravel-gmail-mailer

v1.1.0 2026-11-04 08:22 UTC

Requires

• php: ^8.2
• google/apiclient: ^2.15
• illuminate/contracts: ^12.0|^13.0
• illuminate/mail: ^12.0|^13.0
• illuminate/support: ^12.0|^13.0
• symfony/mailer: ^7.0|^8.0
• symfony/mime: ^7.0|^8.0

Requires (Dev)

• orchestra/testbench: ^10.0|^11.0
• phpunit/phpunit: ^11.0|^12.0

MIT

• Orangesoft

• mail
• mailer
• oauth2
• laravel
• transport
• gmail

Published on Packagist.org on 2026-11-04 08:23 UTC

README

A Laravel mail transport using Gmail API with OAuth2 authentication. This package provides a secure alternative to SMTP for sending emails through Gmail.

Requirements

• PHP 8.2+
• Laravel 12 or 13 (use ^1.0.3 for Laravel 9–11)
• A Google Cloud project with Gmail API enabled

Features

• Sends the exact MIME message Laravel builds: HTML + plain-text parts, attachments, inline images and custom headers
• To, Cc and Bcc recipients (including Mail::alwaysBcc() and envelope recipients)
• Automatic OAuth token refresh before every send, so long-running queue workers keep working
• The Google client is created lazily — resolving the mailer never touches the filesystem or network

Installation

Install the package via Composer:

composer require orange-soft/laravel-gmail-mailer

The package will auto-register its service provider.

Publish Configuration

php artisan vendor:publish --tag=gmail-mailer-config

Google Cloud Setup

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Gmail API:
   • Navigate to "APIs & Services" > "Library"
   • Search for "Gmail API" and enable it
4. Create OAuth2 credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Select "Desktop app" as the application type
   • Download the credentials JSON file
5. Save the credentials file:
   • Default location: storage/app/gmail/credentials.json
   • Or set a custom path via GMAIL_CREDENTIALS_PATH

Setup OAuth Token

Run the setup command to authenticate with your Google account:

php artisan os:gmail-mailer:setup

This will:

1. Display an authorization URL
2. Ask you to open the URL in your browser and grant access
3. Redirect your browser to http://localhost — the page will fail to load, which is expected
4. Ask you to paste that full redirected URL (it contains ?code=...)
5. Save the OAuth token for future use

Google retired the copy/paste "out-of-band" flow in 2023; this package uses the loopback redirect that Desktop app OAuth clients accept. Pass --redirect-uri= to use a different loopback address.

Configuration

Environment Variables

Add to your .env file:

MAIL_MAILER=gmail-oauth2

# Optional: Custom paths for credentials and token
GMAIL_CREDENTIALS_PATH=/path/to/credentials.json
GMAIL_TOKEN_PATH=/path/to/token.json

# Optional: Application name shown in Google OAuth consent
GMAIL_APP_NAME="My Application"

# Optional: Default test recipient for the test command
GMAIL_TEST_RECIPIENT=[e-mail]

# Optional: Logging
GMAIL_LOGGING_ENABLED=true
GMAIL_LOG_CHANNEL=stack

Mail Configuration

Add the Gmail mailer to your config/mail.php:

'mailers' => [
    // ... other mailers

    'gmail-oauth2' => [
        'transport' => 'gmail-oauth2',
    ],
],

Usage

Send Email via Laravel Mail Facade

use Illuminate\Support\Facades\Mail;
use App\Mail\WelcomeEmail;

// Send using the default mailer (when MAIL_MAILER=gmail-oauth2)
Mail::to('[e-mail]')->send(new WelcomeEmail());

// Or explicitly use the Gmail mailer
Mail::mailer('gmail-oauth2')
    ->to('[e-mail]')
    ->send(new WelcomeEmail());

Attachments

Attachments, inline images and plain-text alternatives work exactly as with any other Laravel mailer:

Mail::to('[e-mail]')->send(
    (new InvoiceMail($invoice))->attach(storage_path('invoices/123.pdf'))
);

Direct Service Usage

use Orangesoft\GmailMailer\Services\GmailService;

$gmail = app(GmailService::class);

$gmail->sendEmail(
    to: '[e-mail]',
    subject: 'Hello World',
    body: '<h1>Welcome!</h1><p>This is a test email.</p>',
    options: [
        'from' => '[e-mail]',
        'fromName' => 'My App',
        'cc' => ['[e-mail]'],
        'bcc' => ['[e-mail]'],
        'replyTo' => '[e-mail]',
    ]
);

Commands

Setup OAuth

php artisan os:gmail-mailer:setup

# With custom paths
php artisan os:gmail-mailer:setup --credentials=/path/to/credentials.json --token=/path/to/token.json

Test Email

# Send a test email
php artisan os:gmail-mailer:test [e-mail]

# With custom subject
php artisan os:gmail-mailer:test [e-mail] --subject="Custom Subject"

# Check token status only (no email sent)
php artisan os:gmail-mailer:test --check-only

Token Refresh

The package refreshes expired access tokens automatically before each send (and writes the new token back to token.json). If the refresh token itself is revoked or expires — e.g. your OAuth consent screen is still in "Testing" mode, where Google expires refresh tokens after 7 days — re-run:

php artisan os:gmail-mailer:setup

Troubleshooting

Token Expired Error

If you see "Gmail OAuth token has expired and cannot be refreshed", run:

php artisan os:gmail-mailer:setup

Credentials Not Found

Ensure your credentials file exists at the configured path:

ls -la storage/app/gmail/credentials.json

Permission Denied

Check file permissions:

chmod 600 storage/app/gmail/token.json
chmod 600 storage/app/gmail/credentials.json

Check Configuration

Verify your setup:

php artisan os:gmail-mailer:test --check-only

Keeping vendor small

google/apiclient ships client classes for every Google API (~30k files). Since only Gmail is used, you can strip the rest in your application's composer.json:

"scripts": {
    "pre-autoload-dump": "Google\\Task\\Composer::cleanup"
},
"extra": {
    "google/apiclient-services": ["Gmail"]
}

Only do this if your application doesn't use other Google API services.

Testing

composer test

Security

• OAuth tokens are stored with restricted permissions (0600)
• Credentials and tokens should be added to .gitignore
• Never commit credential or token files to version control

Add to your .gitignore:

storage/app/gmail/credentials.json
storage/app/gmail/token.json

License

This package is open-sourced software licensed under the MIT license.