Gmail API package for Laravel

v5.1.21 2021-08-09 14:15 UTC


Build Status Scrutinizer Code Quality GitHub issues Total Downloads Monthly Downloads GitHub license


Gmail API for Laravel 8

You need to create an application in the Google Console. Guidance here.

if you need Laravel 5 compatibility please use version 2.0.x. if you need Laravel 6 compatibility please use version 3.0.x. if you need Laravel 7 compatibility please use version 4.0.x.


  • PHP ^7.4|^8.0
  • Laravel 8


Add dacastro4/laravel-gmail to composer.json.

"dacastro4/laravel-gmail": "^5.1"

Run composer update to pull down the latest version.

Or run

composer require dacastro4/laravel-gmail

Now open up config/app.php and add the service provider to your providers array.

'providers' => [

Now add the alias.

'aliases' => [
    'LaravelGmail' => Dacastro4\LaravelGmail\Facade\LaravelGmail::class,

For laravel >=5.5 that's all. This package supports Laravel new Package Discovery.

For <= PHP 7.4 compatibility use version v5.0

Migration from 4.0 to 5.0

Requires Laravel 8 and you have to change the dependency to "laravel/laravel": "^8.0" Please, follow Upgrading To 8.0 From 6.x Guide

Migration from 3.0 to 4.0

Requires Laravel 7 and you have to change the dependency to "laravel/laravel": "^7.0" Please, follow Upgrading To 7.0 From 6.x Guide

Migration from 2.0 to 3.0

Requires Laravel 6 and you only have to change the dependency to "laravel/laravel": "^6.0"

Migration from 1.0 to 2.0

The only changed made was the multi credentials feature.

  • Change your composer.json from "dacastro4/laravel-gmail": "^1.0" to "dacastro4/laravel-gmail": "^2.0"

I had to change version because of a typo and that might break apps calling those attributes.

All variable with the word "threat" was change to "thread" (yeah, I know.. sorry) Ex:

Mail Class $threatId => $threadId

Replyable Class $mail->setReplyThreat() => $mail->setReplyThread()

and so on.

Migration from 0.6 to 1.0

The only changed made was the multi credentials feature.

  • Change your composer.json from "dacastro4/laravel-gmail": "^0.6" to "dacastro4/laravel-gmail": "^1.0"

If you don't want the multi user credentials, you don't have to do anything else, if you do, you're going to have to login again to create a new credentials file per user.


You only have to set the following variables on your .env file and you'll be on your way:


To modify the scopes and the credentials file name, just run:

Run php artisan vendor:publish --provider="Dacastro4\LaravelGmail\LaravelGmailServiceProvider" and modify the config file config/gmail.php.

Allow multi user credentials

To allow multi user credentials change allow_multiple_credentials to true in your config file or set the .env variable GOOGLE_ALLOW_MULTIPLE_CREDENTIALS to true if you're not using the config file.

Allow encryption for json files

To allow encryption for json files change allow_json_encrypt to true in your config file or set the .env variable GOOGLE_ALLOW_JSON_ENCRYPT to true if you're not using the config file.

Available Scopes

  • all (this one doesn't exists on Gmail Scopes, I added it.)
  • compose
  • insert
  • labels
  • metadata
  • modify
  • readonly
  • send
  • settings_basic
  • settings_sharing

More about Gmail API scopes

Note: To change the scopes, users have to logout and login again.

Additional Scopes

If for some reason you need to add additional scopes.

Add additional scopes in URL Style in config/gmail.php

 'additional_scopes' => [


Welcome Blade:

    <h1>{{ LaravelGmail::user() }}</h1>
        <a href="{{ url('oauth/gmail/logout') }}">logout</a>
        <a href="{{ url('oauth/gmail') }}">login</a>


Route::get('/oauth/gmail', function (){
    return LaravelGmail::redirect();

Route::get('/oauth/gmail/callback', function (){
    return redirect()->to('/');

Route::get('/oauth/gmail/logout', function (){
    LaravelGmail::logout(); //It returns exception if fails
    return redirect()->to('/');

Then if in your controller or wherever you want to do your logic, you do something like:

$messages = LaravelGmail::message()->subject('test')->unread()->preload()->all();
foreach ( $messages as $message ) {
    $body = $message->getHtmlBody();
    $subject = $message->getSubject();

Note that if you don't preload the messages you have to do something like: $body = $message->load()->getSubject(); and after that you don't have to call it again.



LaravelGmail::getAuthUrl Gets the URL to auth the user.

LaravelGmail::redirect You can use this as a direct method <a href="{{ LaravelGmail::redirect() }}">Login</a>

LaravelGmail::makeToken() Set and Save AccessToken in json file (useful in the callback)

LaravelGmail::logout Logs out the user

LaravelGmail::check Checks if the user is logged in

LaravelGmail::setUserId($account_id)->makeToken() Set and Save AccessToken for $account_id (added v5.1.2)


use Dacastro4\LaravelGmail\Services\Message\Mail;


$mail = new Mail;

For to, from, cc and bcc, you can set an array of emails and name or a string of email and name.

$mail->using( $token ) If you don't want to use the token file, you can use this function that sets the token to use in the request. It doesn't refresh

$mail->to( $to, $name = null ) sets the recipient email and name as optional

$mail->from( $from, $name = null ) sets sender's email

$mail->cc( $cc, $name = null ) sets carbon copy

$mail->bcc( $bcc, $name = null ) sets a blind carbon copy

$mail->subject( $subject ) sets the subject of the email

$mail->message( $message ) sets the body of the email

$mail->view( 'view.name', $dataArray ) sets the body from a blade file

$mail->attach( ...$path ) add file attachments to the email

$mail->priority( $priority ) sets the priority of the email from 1 to 5

$mail->reply() replies to an existent email

$mail->send() sends a new email

$mail->setHeader( $header, $value ) sets header to the email


$mail->getId returns the email's ID

$mail->getInternalDate returns date in UNIX format

$mail->getDate returns a Carbon date from the header of the email

$mail->getLabels returns an array of all the labels of the email

$mail->getHeaders returns a collection of the header. Each header is an array with two rows key and value

$mail->getSubject returns an string of the subject

$mail->getFrom Returns an array with name and email of sender

$mail->getFromName Returns string of name

$mail->getFromEmail Returns string of email

$mail->getTo Returns an array with name and email of all recipients

$mail->getDeliveredTo Returns the email of the receiver

$mail->getPlainTextBody Returns the plain text version of the email

$mail->getRawPlainTextBody Returns the raw version of the body base64 encrypted

$mail->hasAttachments Returns a boolean if the email has attachments

$mail->load Load all the information of the email (labels, body, headers). You call this function on a single email. To load from the beginning see preload()

$mail->getHeader( $headerName, $regex = null ) Returns the header by name. Optionally, you can execute a regex on the value


$mail->markAsRead Removes the 'UNREAD' label from the email.

$mail->markAsUnread Adds the 'UNREAD' label to the email.

$mail->markAsImportant Adds the 'IMPORTANT' label to the email.

$mail->markAsNotImportant Removes the 'IMPORTANT' label from the email.

$mail->addStar Adds the 'STARRED' label to the email.

$mail->removeStar Removes the 'STARRED' label from the email.

$mail->sendToTrash Adds the 'TRASH' label to the email.

$mail->removeFromTrash Removes the 'TRASH' label from the email.

$mail->addLabel($string|$array) Add multiple or single label to the email

$mail->removeLabel($string|$array) Removes multiple or single label from the email

$mail->getAttachments() Get a collection of all the attachments on the email

$mail->getAttachmentsWithData() Get a collection of all the attachments on the email including the data


use Dacastro4\LaravelGmail\Services\Message\Attachment

$attachment = new Attachment;

$attachment->getId Returns the ID of the attachment

$attachment->getFileName Returns the file name of the attachment

$attachment->getMimeType Returns the mime type Ex: application/pdf

$attachment->getSize Returns the size of the attachment in bytes

$attachment->getData Get the all the information from the attachment. If you call getAttachmentsWithData you won't need this method.

$attachment->saveAttachmentTo($path = null, $filename = null, $disk = 'local') Saves the attachment on the storage folder. You can pass the path, name and disk to use.


LaravelGmail::message()->all( $pageToken = null ) Returns all the emails from the inbox

LaravelGmail::message()->take(2)->all( $pageToken = null ) The take method limits the emails coming from the query by the number set

LaravelGmail::message()->get( $id ) Returns a single email with all the information


You can modify your query with these methods. For example:

To get all unread emails: LaravelGmail::message()->unread()->all()


message()->from( $email )

message()->in( $box = 'inbox' )



->after($date) and ->before($date)

message()->raw($query) for customized queries

All the possible filters are in the Filterable Trait

Of course you can use as a fluent api.



You can preload the body, header and the rest of every single email just by calling this method.







    $mailbox = new LaravelGmailClass(config(), $account->id);
    // One watch per account + need reinit every 24h+

    // Set watch for topic
    $rq = new \Google_Service_Gmail_WatchRequest();
    $mailbox->setWatch('example@gmail.com', $rq);




    $historyList = (new LaravelGmailClass(config(), $account->id))
        ->historyList($data['emailAddress'], [
            'startHistoryId' => $startHistoryId,
    foreach ($historyList->history as $chunk) {
        foreach ($chunk->messages as $msg) {

Frequent Issues

Login Required

If you're getting the Login Required error, try creating the gmail-json.json file under /storage/app/gmail/tokens/.