README

Email plugin module for the REUT framework providing SMTP email sending functionality.

Installation

Install the package via Composer:

composer require reut/email

Configuration

Add the following environment variables to your .env file:

REUT_EMAIL_ENABLED=true
REUT_EMAIL_REQUIRES_AUTH=false
REUT_EMAIL_SMTP_HOST=smtp.gmail.com
REUT_EMAIL_SMTP_PORT=587
REUT_EMAIL_SMTP_USERNAME=your-email@gmail.com
REUT_EMAIL_SMTP_PASSWORD=your-app-password
REUT_EMAIL_SMTP_ENCRYPTION=tls
REUT_EMAIL_FROM_ADDRESS=noreply@example.com
REUT_EMAIL_FROM_NAME=REUT Framework

Configuration Options

REUT_EMAIL_ENABLED - Enable/disable email functionality (default: false)
REUT_EMAIL_REQUIRES_AUTH - Require JWT authentication for email endpoints (default: false)
REUT_EMAIL_SMTP_HOST - SMTP server hostname (required)
REUT_EMAIL_SMTP_PORT - SMTP server port (default: 587)
REUT_EMAIL_SMTP_USERNAME - SMTP username (optional if no authentication)
REUT_EMAIL_SMTP_PASSWORD - SMTP password (optional if no authentication)
REUT_EMAIL_SMTP_ENCRYPTION - Encryption type: tls, ssl, or empty (default: tls)
REUT_EMAIL_FROM_ADDRESS - Default from email address (required)
REUT_EMAIL_FROM_NAME - Default from name (default: REUT Framework)

Integration

Add the email router to your project's routers/routes.php:

<?php

use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Reut\Auth\AuthRouter;
use Reut\Router\DocsController;
use Reut\Router\SchemaController;
use Reut\Router\ReuteRoute;
use Reut\Email\EmailRouter;
use Reut\Email\Config\EmailConfig;
use Slim\App;

return function (App $app, array $config): void {
    // ... existing routes ...

    // Register email routes
    if ((strtolower($_ENV['REUT_EMAIL_ENABLED'] ?? 'false')) === 'true') {
        $emailConfig = EmailConfig::load();
        if (EmailConfig::isEnabled($emailConfig)) {
            new EmailRouter($app, $config, $emailConfig);
        }
    }
};

Authentication

By default, email endpoints are publicly accessible. To require JWT authentication for all email endpoints, set:

REUT_EMAIL_REQUIRES_AUTH=true

When enabled, all requests to email endpoints must include a valid JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

API Endpoints

Send Email

POST /email/send

Send an email via SMTP.

Authentication: Optional (controlled by REUT_EMAIL_REQUIRES_AUTH)

Request Body:

{
    "to": "recipient@example.com",
    "subject": "Hello from REUT",
    "body": "<h1>Hello</h1><p>This is a test email.</p>",
    "bodyType": "html",
    "cc": "cc@example.com",
    "bcc": ["bcc1@example.com", "bcc2@example.com"],
    "replyTo": "reply@example.com",
    "replyToName": "Reply Name"
}

Response (Success):

{
    "success": true,
    "message": "Email sent successfully"
}

Response (Error):

{
    "error": true,
    "message": "Validation failed",
    "errors": ["to field is required"]
}

Check Status

GET /email/status

Check email service status and configuration.

Authentication: Optional (controlled by REUT_EMAIL_REQUIRES_AUTH)

Response:

{
    "status": "ok",
    "smtp_configured": true,
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "from_address": "noreply@example.com",
    "errors": []
}

Usage Examples

Basic Email Sending

use Reut\Email\EmailService;
use Reut\Email\Config\EmailConfig;

$emailConfig = EmailConfig::load();
$emailService = new EmailService($emailConfig);

try {
    $emailService->send(
        'user@example.com',
        'Welcome!',
        '<h1>Welcome to our service</h1>',
        'html'
    );
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Email with Options

$emailService->send(
    'user@example.com',
    'Invoice',
    '<p>Please find your invoice attached.</p>',
    'html',
    [
        'cc' => 'manager@example.com',
        'bcc' => ['archive@example.com'],
        'replyTo' => 'support@example.com',
        'attachments' => [
            '/path/to/invoice.pdf',
            [
                'path' => '/path/to/receipt.pdf',
                'name' => 'receipt.pdf'
            ]
        ]
    ]
);

Requirements

PHP >= 7.4
REUT Core ^1.1
PHPMailer ^6.9

License

MIT License

Support

For issues and questions, please visit: https://github.com/m4rcTr3y/Reut-Email/issues

reut / email

Maintainers

Details