📧 SPP Email Service API

A dynamic email service API for the eSPP project with support for multiple email providers.

🚀 Supported Providers

Provider Keys

Provider Key	Description
smtp	Standard SMTP server (configured via SMTP_* env vars)
office365	Office 365 SMTP (configured via OFFICE365_* env vars)
imap	IMAP-backed account (uses SMTP settings in IMAP_SMTP_* env vars for sending)
pop3	POP3-backed account (uses SMTP settings in POP3_SMTP_* env vars for sending)
mailtrap	Mailtrap testing inbox (useful for staging/testing; configured via MAILTRAP_* env vars)

📍 API Endpoint

📋 Request Parameters

Send a JSON body (Content-Type: application/json) with the fields below. The API only accepts POST requests to /api.php.

Parameter	Type	Required	Description
to	array	Yes	Array of recipient email addresses
from	string	Yes	Sender email address (displayed in recipient client). If provider policy disallows custom From, the authenticated envelope sender will be used and Reply-To will be set to this value.
from_name	string	No	Optional human-readable name for the sender (e.g. "Acme Inc."). When provided, it will be used with the from address as the display name.
subject	string	Yes	Email subject
body	string	Yes	HTML content of the email
cc	array	No	Array of CC email addresses
bcc	array	No	Array of BCC email addresses
provider	string	No	Email provider (default: value of DEFAULT_EMAIL_PROVIDER in .env). Options (keys): smtp, office365, imap, pop3, mailtrap. Provider name is case-insensitive and common variants such as office_365 are accepted.
send_mode	string	No	immediate (default) sends right away inside the API request. Set to queue to enqueue the email in sys_email_queue, return a 202 response with job_id, and let the worker deliver it later.

Provider policy

Each provider can be configured to allow or disallow caller-supplied from addresses via environment flags (for example SMTP_ALLOW_CUSTOM_FROM). When a provider disallows custom From addresses, the service will:

• Use the provider's authenticated account as the envelope sender (MAIL FROM).
• Set the displayed From to the closest allowed address and add Reply-To to the caller-specified from so replies go to the original sender.

This preserves deliverability while letting callers request a custom display sender when permitted.

💡 Example Request

cURL example (replace values as needed):

curl -X POST "http://localhost:8000/api.php" \
  -H "Content-Type: application/json" \
  -d '{
  "to": ["recipient@example.com"],
  "from": "sender@example.com",
  "from_name": "Acme Inc.",
  "subject": "Test Email",
  "body": "<h1>Hello!</h1><p>This is a test email.</p>",
  "cc": ["cc@example.com"],
  "provider": "smtp"
}'

Notes:

• If provider is omitted, the service uses the DEFAULT_EMAIL_PROVIDER from .env.
• Use from_name to control the display name shown in email clients.
• Provider policies (environment flags like SMTP_ALLOW_CUSTOM_FROM) control whether arbitrary from addresses are accepted. If disallowed, the envelope sender will be the authenticated account and a Reply-To will be set so replies go to the requested from.

✅ Success Response

{
  "status": "success",
  "code": 200,
  "message": "Email sent successfully",
  "effective_from": "no-reply@customdomain.com",    // shown From address
  "envelope_from": "espp@metadatasystem.my",      // SMTP envelope sender used for delivery
  "from_overridden": false                           // true if caller-supplied From was overridden by provider policy
}

Queued mode returns:

{
    "status": "queued",
    "code": 202,
    "message": "Email request enqueued for processing",
    "job_id": 123,
    "available_at": "2025-11-22T21:24:11+08:00"
}

❌ Error Response

{
  "status": "error",
  "code": 400,
  "message": "Missing required field: to"
}

🔧 Setup

1. Copy .env.example to .env
2. Configure your email provider settings in .env
3. Ensure PHP and Composer are installed
4. Run composer install to install dependencies
5. Send POST requests to /public/api.php

📚 Documentation

For detailed documentation, examples, and how to add new providers, please see the README.md file.

🔍 → Interactive API Documentation (Swagger UI)

🔗 Test the API

Use tools like Postman, cURL, or the example code provided in examples.php to test the API.

🧰 Queue Runner Endpoint

Shared-hosting cron tools (such as Plesk “Fetch a URL”) can invoke the lightweight queue runner:

• Set QUEUE_RUNNER_TOKEN in .env (recommended) so only authorized jobs can trigger it.
• max_jobs and channel query params are optional overrides; otherwise defaults come from QUEUE_RUNNER_MAX_JOBS and QUEUE_CHANNEL.
• Each hit processes a short batch via the same worker logic as bin/queue-work-once.php and returns JSON with processed_jobs for monitoring.

📊 Queue Monitor Dashboard

Need a quick snapshot of what’s stuck? Visit /queue-admin.php (HTTPS recommended) and supply ?token=YOUR_QUEUE_ADMIN_TOKEN if configured. The page shows status counts, the 50 latest jobs, and per-job logs when you enter a Job ID.