Download the PHP package partridgerocks/gmail-client without Composer

Laravel Gmail Client

A Laravel package that integrates with the Gmail API to seamlessly manage emails within your application. Built with Saloon PHP for API interactions and Laravel Data for structured data handling.

📋 Table of Contents

• Features
• Requirements
• Installation
• Google API Setup
• Usage
  • Authentication
  • Working with Emails
  • Working with Labels
  • Using Without Facade
  • Integration with User Model
• Advanced Usage
  • Pagination
  • Memory-Efficient Processing
  • Error Handling
  • Token Refreshing
  • CLI Testing
  • Custom Templates
• Events
• Testing
• Changelog
• Contributing
• Security
• Credits
• License

🚀 Features

• OAuth Authentication: Seamless integration with Gmail's OAuth 2.0 flow
• Email Operations:
  • Read emails and threads with full content and attachments
  • Send emails with HTML content
  • Support for CC, BCC, and custom sender addresses
• Label Management:
  • List, create, update, and delete email labels
  • Organize emails with custom label hierarchies
• Performance Optimizations:
  • Lazy loading collections for memory-efficient processing
  • Pagination support for large datasets
  • Customizable batch sizes for API requests
• Developer Experience:
  • Laravel facade for convenient access
  • Strongly-typed data objects with Laravel Data
  • Full Laravel service container integration
  • Comprehensive exception handling
  • Command-line testing utilities

📋 Requirements

• PHP 8.2 or higher
• Laravel 10.x, 11.x, or 12.x
• Google API credentials

📦 Installation

You can install the package via Composer:

After installation, publish the configuration file:

This will create a config/gmail-client.php configuration file in your project.

🔐 Google API Setup

Before you can use the Gmail Client, you need to set up a project in the Google Developer Console and obtain OAuth 2.0 credentials:

1. Go to the Google Developer Console
2. Create a new project (or select an existing one)
3. Navigate to "APIs & Services" > "Library"
4. Search for and enable the "Gmail API"
5. Go to "APIs & Services" > "Credentials"
6. Click "Configure Consent Screen" and set up your OAuth consent screen:
   • Select "External" or "Internal" user type (depending on your needs)
   • Fill in the required app information
   • Add the required scopes (see below)
   • Add test users if needed (for external user type)
7. Create OAuth 2.0 credentials:
   • Go to "Credentials" and click "Create Credentials" > "OAuth client ID"
   • Select "Web application" as the application type
   • Add a name for your client
   • Add your authorized redirect URIs (this should match your GMAIL_REDIRECT_URI config value)
   • Click "Create"
8. Copy the Client ID and Client Secret to your .env file:

Note: The Gmail API requires specific scopes to access different features. The default configuration includes commonly used scopes, but you can customize them in the config file.

🔍 Usage

The package automatically registers a Laravel Facade that provides a convenient way to interact with the Gmail API:

Authentication

The Gmail Client provides two ways to authenticate with the Gmail API:

1. Manual Authentication Flow

If you want full control over the authentication process:

2. Using Built-in Routes

For a simpler setup, you can enable the built-in routes:

1. Enable route registration in the config file:

2. Use the provided routes in your app:

The package will handle the OAuth flow and store the tokens in the session by default.

Working with Emails

Once authenticated, you can use the client to interact with Gmail:

List Messages

Get a Specific Message

Send an Email

Working with Labels

Gmail uses labels to organize emails. You can create, retrieve, and manage these labels:

Using Without Facade

If you prefer not to use the facade, you can resolve the client from the container:

Integration with Your User Model

Here's an example of how you might integrate the Gmail client with your User model:

🔧 Advanced Usage

Pagination Support

The package supports pagination for listing messages and labels:

Memory Efficiency

When working with large Gmail accounts, it's important to avoid loading all messages into memory at once:

Enhanced Error Handling

The package provides detailed error handling for common Gmail API errors:

Refresh a Token

Command Line Testing

The package includes a command to test your Gmail API connection:

Custom Email Templates

You can use your own branded email templates:

📡 Events

The package dispatches events that you can listen for:

• GmailAccessTokenRefreshed: When a token is refreshed
• GmailMessageSent: When an email is sent

🧪 Testing

The package includes tests that you can run with PHPUnit:

For testing in your own application, you can use Saloon's built-in mocking capabilities:

📝 Changelog

Please see CHANGELOG for more information on what has changed recently.

🤝 Contributing

Please see CONTRIBUTING for details.

🔒 Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

👨‍💻 Credits

• Jordan Partridge
• All Contributors

📄 License

The MIT License (MIT). Please see License File for more information.