README

A powerful, framework-agnostic PHP package for sending emails via Microsoft Graph API with OAuth 2.0 authentication. Works seamlessly with Laravel, CodeIgniter, Yii, and vanilla PHP projects.

✨ Features

🚀 Microsoft Graph API - Most reliable email delivery method with "Send mail as any user" capability
🔐 OAuth 2.0 Security - No password storage required
🔄 Automatic Token Refresh - Seamless token management
🏗️ Framework Agnostic - Works with any PHP framework
📧 Rich Email Support - HTML, text, templates, attachments
🎯 Laravel Integration - Service provider with auto-discovery
📁 File-based Storage - No database required for tokens
🛠️ Easy Configuration - Simple setup with environment variables
🐛 Debug Mode - Comprehensive logging and error handling
📦 Production Ready - Tested and optimized for production use

📦 Installation

Via Composer

composer require agabaandre-office365/exchange-email-service

Manual Installation

Download the package
Extract to your project directory
Run composer install

🚀 Quick Start

Vanilla PHP

<?php
require_once 'vendor/autoload.php';

use AgabaandreOffice365\ExchangeEmailService\ExchangeEmailService;

// Quick setup with configuration
$emailService = new ExchangeEmailService([
    'tenant_id' => 'your-tenant-id',
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'from_email' => 'noreply@yourdomain.com',
    'from_name' => 'Your App Name'
]);

// Send email
$emailService->sendEmail(
    'recipient@example.com',
    'Hello World!',
    '<h1>Hello!</h1><p>This is a test email.</p>',
    true // HTML email
);

Laravel Integration

Install the package:

composer require agabaandre-office365/exchange-email-service

Publish configuration:

php artisan vendor:publish --provider="AgabaandreOffice365\ExchangeEmailService\ExchangeEmailServiceProvider"

Configure environment variables in .env:

EXCHANGE_TENANT_ID=your-tenant-id
EXCHANGE_CLIENT_ID=your-client-id
EXCHANGE_CLIENT_SECRET=your-client-secret
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="Your App Name"

Use in your application:

use AgabaandreOffice365\ExchangeEmailService\ExchangeEmailService;

class EmailController extends Controller
{
    public function sendEmail(ExchangeEmailService $emailService)
    {
        $emailService->sendEmail(
            'recipient@example.com',
            'Hello from Laravel!',
            '<h1>Hello!</h1><p>This email was sent from Laravel.</p>'
        );
    }
}

⚙️ Configuration

Environment Variables

Variable	Description	Required	Default
`EXCHANGE_TENANT_ID`	Azure AD Tenant ID	✅	-
`EXCHANGE_CLIENT_ID`	Azure AD Application ID	✅	-
`EXCHANGE_CLIENT_SECRET`	Azure AD Application Secret	✅	-
`EXCHANGE_REDIRECT_URI`	OAuth Redirect URI	❌	`http://localhost:8000/oauth/callback`
`EXCHANGE_SCOPE`	OAuth Scope	❌	`https://graph.microsoft.com/.default`
`EXCHANGE_AUTH_METHOD`	Authentication Method	❌	`client_credentials`
`MAIL_FROM_ADDRESS`	Default From Email	✅	-
`MAIL_FROM_NAME`	Default From Name	❌	`Exchange Email Service`

Configuration Array

$config = [
    'tenant_id' => 'your-tenant-id',
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'redirect_uri' => 'https://yourdomain.com/oauth/callback',
    'scope' => 'https://graph.microsoft.com/.default',
    'auth_method' => 'client_credentials', // or 'authorization_code'
    'from_email' => 'noreply@yourdomain.com',
    'from_name' => 'Your App Name',
    'token_storage' => [
        'type' => 'file',
        'path' => 'storage/exchange-email-tokens.json',
        'permissions' => 0644,
    ],
    'defaults' => [
        'is_html' => true,
        'timeout' => 30,
        'retry_attempts' => 3,
        'debug' => false,
    ]
];

📧 Usage Examples

Basic Email Sending

// Send HTML email
$emailService->sendHtmlEmail(
    'recipient@example.com',
    'HTML Email',
    '<h1>Hello!</h1><p>This is an HTML email.</p>'
);

// Send text email
$emailService->sendTextEmail(
    'recipient@example.com',
    'Text Email',
    'Hello! This is a plain text email.'
);

// Send email with custom from address
$emailService->sendEmail(
    'recipient@example.com',
    'Custom From Email',
    '<p>This email has a custom from address.</p>',
    true,
    'custom@yourdomain.com',
    'Custom Sender'
);

Email with CC and BCC

$emailService->sendEmail(
    'recipient@example.com',
    'Email with CC/BCC',
    '<p>This email has CC and BCC recipients.</p>',
    true,
    null, // from_email (uses default)
    null, // from_name (uses default)
    ['cc@example.com'], // CC recipients
    ['bcc@example.com'] // BCC recipients
);

Email with Attachments

$attachments = [
    [
        'name' => 'document.pdf',
        'content' => file_get_contents('path/to/document.pdf'),
        'content_type' => 'application/pdf'
    ],
    [
        'name' => 'image.jpg',
        'content' => file_get_contents('path/to/image.jpg'),
        'content_type' => 'image/jpeg'
    ]
];

$emailService->sendEmail(
    'recipient@example.com',
    'Email with Attachments',
    '<p>Please find the attached files.</p>',
    true,
    null, // from_email
    null, // from_name
    [], // CC
    [], // BCC
    $attachments
);

Template Emails

$template = '
    <h1>Welcome {{name}}!</h1>
    <p>Your order #{{order_id}} is confirmed.</p>
    <p>Total: ${{total}}</p>
    <p>Thank you for choosing {{app_name}}!</p>
';

$data = [
    'name' => 'John Doe',
    'order_id' => '12345',
    'total' => '99.99',
    'app_name' => 'My Store'
];

$emailService->sendTemplateEmail(
    'recipient@example.com',
    'Order Confirmation',
    $template,
    $data
);

Bulk Email Sending

$recipients = [
    'user1@example.com',
    'user2@example.com',
    'user3@example.com'
];

$emailService->sendBulkEmail(
    $recipients,
    'Newsletter',
    '<h1>Monthly Newsletter</h1><p>Check out our latest updates!</p>'
);

🔐 Azure AD Setup

1. Create Azure AD Application

Go to Azure Portal
Navigate to Azure Active Directory > App registrations
Click New registration
Fill in details:
- Name: Your Email Service
- Redirect URI: https://yourdomain.com/oauth/callback (for authorization code flow)
Note down Application (client) ID and Directory (tenant) ID

2. Create Client Secret

Go to your app > Certificates & secrets
Click New client secret
Add description: "Email Service Secret"
Copy the secret value (you won't see it again!)

3. Grant Permissions

Go to your app > API permissions
Click Add a permission
Select Microsoft Graph
Choose Application permissions
Add Mail.Send permission (https://graph.microsoft.com/Mail.Send)
Click Grant admin consent

Important: The application requires the Mail.Send application permission with "Send mail as any user" capability. This allows the service to send emails on behalf of any user in your organization via Microsoft Graph API.

4. Configure Redirect URI (for Authorization Code flow)

Go to your app > Authentication
Add your redirect URI: https://yourdomain.com/oauth/callback

🔄 Authentication Methods

Client Credentials Flow (Recommended for Server Applications)

$config = [
    'tenant_id' => 'your-tenant-id',
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'auth_method' => 'client_credentials',
    'from_email' => 'noreply@yourdomain.com',
    'from_name' => 'Your App Name'
];

Authorization Code Flow (For User-based Applications)

$config = [
    'tenant_id' => 'your-tenant-id',
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'redirect_uri' => 'https://yourdomain.com/oauth/callback',
    'auth_method' => 'authorization_code',
    'from_email' => 'noreply@yourdomain.com',
    'from_name' => 'Your App Name'
];

// Get authorization URL
$authUrl = $emailService->getAuthorizationUrl();

// After user authorizes, exchange code for token
$emailService->exchangeCodeForToken($code, $state);

🛠️ Advanced Usage

Token Management

// Get token information
$tokenInfo = $emailService->getTokenInfo();
echo "Token expires in: " . $tokenInfo['expires_in'] . " seconds\n";

// Clear stored tokens (useful for logout)
$emailService->clearTokens();

// Check if service is configured
if ($emailService->isConfigured()) {
    echo "Email service is ready!";
} else {
    echo "Email service needs configuration.";
}

Token Storage

The package uses intelligent file-based storage that automatically finds the best writable location:

Project Root - storage/exchange-email-tokens.json (recommended)
System Temp - /tmp/exchange-email-tokens/ (fallback)
User Home - ~/.exchange-email-tokens/ (fallback)
Current Directory - ./storage/ (fallback)

No vendor directory issues - The package automatically avoids writing to the vendor directory and finds a writable location.

Error Handling

try {
    $result = $emailService->sendEmail(
        'recipient@example.com',
        'Test Email',
        '<p>This is a test email.</p>'
    );
    
    if ($result) {
        echo "Email sent successfully!";
    } else {
        echo "Failed to send email.";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
    // Log the error for debugging
    error_log($e->getTraceAsString());
}

Debug Mode

$config = [
    // ... other config
    'defaults' => [
        'debug' => true,
    ]
];

$emailService = new ExchangeEmailService($config);
// Debug information will be logged

🧪 Testing

Test Email Service

use AgabaandreOffice365\ExchangeEmailService\ExchangeEmailService;

$emailService = new ExchangeEmailService([
    'tenant_id' => 'your-tenant-id',
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'from_email' => 'noreply@yourdomain.com',
    'from_name' => 'Your App Name'
]);

// Test connection
$tokenInfo = $emailService->getTokenInfo();
if (!empty($tokenInfo)) {
    echo "✅ Service is ready!";
} else {
    echo "❌ Service needs configuration.";
}

// Send test email
$emailService->sendEmail(
    'test@example.com',
    'Test Email',
    '<h1>Test</h1><p>This is a test email.</p>'
);

🚀 Laravel Integration

Service Provider Registration

The package automatically registers itself with Laravel's service container. You can use it in several ways:

Method 1: Dependency Injection (Recommended)

use AgabaandreOffice365\ExchangeEmailService\ExchangeEmailService;

class EmailController extends Controller
{
    public function sendEmail(ExchangeEmailService $emailService)
    {
        $emailService->sendEmail(
            'recipient@example.com',
            'Hello from Laravel!',
            '<h1>Hello!</h1><p>This email was sent from Laravel.</p>'
        );
    }
}

Method 2: Service Container

$emailService = app(ExchangeEmailService::class);
$emailService->sendEmail(/* ... */);

Method 3: Facade (if registered)

use ExchangeEmail;

ExchangeEmail::sendEmail(/* ... */);

Laravel Jobs

use AgabaandreOffice365\ExchangeEmailService\ExchangeEmailService;

class SendWelcomeEmail implements ShouldQueue
{
    public function handle(ExchangeEmailService $emailService)
    {
        $emailService->sendEmail(
            $this->email,
            'Welcome!',
            '<h1>Welcome to our platform!</h1>'
        );
    }
}

Laravel Commands

use AgabaandreOffice365\ExchangeEmailService\ExchangeEmailService;

class SendTestEmailCommand extends Command
{
    protected $signature = 'email:test {email}';
    
    public function handle(ExchangeEmailService $emailService)
    {
        $result = $emailService->sendEmail(
            $this->argument('email'),
            'Test Email',
            '<h1>Test Email</h1><p>This is a test email from Laravel.</p>'
        );
        
        $this->info($result ? 'Email sent!' : 'Failed to send email.');
    }
}

📋 Requirements

PHP: 7.4 or higher
Extensions: cURL, JSON
Dependencies: Guzzle HTTP client (installed via Composer)
Azure AD: Valid app registration with Mail.Send application permission (Send mail as any user)
Microsoft Graph API: Access to Microsoft Graph API for email sending

🐛 Troubleshooting

Common Issues

"Email service not configured"
- Check your .env file has all required variables
- Ensure OAuth credentials are correct
"AADSTS1002012: The provided value for scope is not valid"
- Use https://graph.microsoft.com/.default for client credentials flow
- Use https://graph.microsoft.com/Mail.Send for authorization code flow
"AADSTS900023: Specified tenant identifier is not valid"
- Check your EXCHANGE_TENANT_ID is correct
- Ensure it's a valid GUID or domain name
"Failed to send email"
- Check recipient email address
- Verify OAuth permissions are granted (https://graph.microsoft.com/Mail.Send)
- Check Azure app registration settings
- Ensure admin consent has been granted for the Mail.Send permission

Debug Mode

Enable debug mode to see detailed logs:

$config = [
    // ... other config
    'defaults' => [
        'debug' => true,
    ]
];

📄 License

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

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

Issues: GitHub Issues
Email: agabaandre@gmail.com
Documentation: GitHub Wiki

🎯 Roadmap

Database token storage option
Email queue support
Advanced template engine
Webhook support
Rate limiting
Email analytics

Made with ❤️ by Andre Agaba

agabaandre-office365 / exchange-email-service

Maintainers

Details

README

✨ Features

📦 Installation

Via Composer

Manual Installation

🚀 Quick Start

Vanilla PHP

Laravel Integration

⚙️ Configuration

Environment Variables

Configuration Array

📧 Usage Examples

Basic Email Sending

Email with CC and BCC

Email with Attachments

Template Emails

Bulk Email Sending

🔐 Azure AD Setup

1. Create Azure AD Application

2. Create Client Secret

3. Grant Permissions

4. Configure Redirect URI (for Authorization Code flow)

🔄 Authentication Methods

Client Credentials Flow (Recommended for Server Applications)

Authorization Code Flow (For User-based Applications)

🛠️ Advanced Usage

Token Management

Token Storage

Error Handling

Debug Mode

🧪 Testing

Test Email Service

🚀 Laravel Integration

Service Provider Registration

Method 1: Dependency Injection (Recommended)

Method 2: Service Container

Method 3: Facade (if registered)

Laravel Jobs

Laravel Commands

📋 Requirements

🐛 Troubleshooting

Common Issues

Debug Mode

📄 License

🤝 Contributing

📞 Support

🎯 Roadmap