Download the PHP package anikninja/mail-mapper without Composer

📬 Mail Mapper for Laravel

Mail Mapper is a standalone Laravel package that provides a dynamic, configurable email mapping and notification system.
It allows administrators or developers to define who receives which emails for specific module actions — without changing application code.

This package is ideal for ERP, CRM, and enterprise Laravel applications where email recipients frequently change.

✨ Features

• Module / Menu / Task based email mapping
• Dynamic To / CC email configuration from database
• Queue-based email dispatching
• Blade-based HTML email template
• Raw mail fallback for strict SMTP servers
• Easy integration using Trait or Helper
• Publishable config, migrations, and views

📦 Installation

Install via Composer:

Publish package resources:

Run migrations:

⚙️ Configuration

Config file location:

Example:

Authorization Configuration

The package provides configurable authorization options for the API and management UI. After publishing config/mail-mapper.php you can set the following under the authorization key (or via env variables):

• roles — array of role names allowed to manage mappings (supports spatie/laravel-permission methods like hasRole/hasAnyRole). Can be set via MAIL_MAPPER_AUTH_ROLES=admin,super-admin.
• permissions — array of permission/gate names to check via $user->can('permission') (e.g. ['email-mapping-configure']).
• allow_super_admin — boolean fallback to allow super-admin role or super-admin-only permission (defaults to true).
• default_allow — boolean default if no roles/permissions match (defaults to false).

Example configuration:

Notes:

• The package registers a default EmailMappingPolicy that respects these settings. Host applications can override the policy or adjust these config values after publishing.
• This approach makes authorization flexible across different auth/permission packages and app conventions.

🗒️ ENV Example:

🧠 Core Concepts

Concept Description:

• Module High-level system area (Sales, SCM, Support)
• Menu Feature name (Lead Generation, Purchase Order)
• Task Action name (Create, Update, Delete)
• To / CC Dynamic email recipients
• Body Email content (HTML supported)

🗄️ Database Structure

Email mappings are stored in:

🚀 Usage

✅ Using Trait (Recommended)

✅ Using Helper Function

Attachments

Pass attachments via the $extra parameter or the model context when calling notifyByMapping(...).

Supported formats:

• In-memory attachment (array with filename, content, mime):

• File path (server file path or stored temporary file):

• Uploaded file (from a request):

Example usage:

Notes:

• The trait will normalize attachments and prefer path-based attach() to avoid loading large files into memory.
• Prefer passing file paths or UploadedFile instances for large files.

Parameters

🔹 Wildcard Matching

The Module, Menu, and Task parameters support the * wildcard to allow flexible mapping rules:

Wildcard support allows you to define general-purpose email templates that apply to multiple actions or modules — reducing redundancy and centralizing notification management.

⚙️ How It Works

1. Context Extraction

Builds a unified context array from the provided model or array, merging any extra data.

2. Meta Placeholder Management

Extracts all placeholders used in templates and stores them in the mapping’s meta field if not already present.

3. Recipient & Template Resolution

Uses EmailMappingService to resolve recipients, subject, and body dynamically, applying context placeholders.

4. Email Dispatch

Dispatches the fully rendered email through SendEmailNotificationJob for queued or asynchronous delivery.

🗒️ Notes

• Ensure your EmailMapping model and database table are properly configured to store mapping definitions and meta placeholders.
• Placeholders in templates (e.g., {client_name}) are automatically replaced with values from the provided context.
• {actor_name} and {actor_email} are injected automatically when an authenticated user exists.

📨 Email Sending Strategy

The package automatically decides how to send email:

1. Mailable (HTML template)
2. Raw mail fallback if SMTP server rejects HTML mailables

You can force raw mode:

🎨 Email Template

Default template:

To customize:

🧪 Queue Requirement

This package uses Laravel queues.

Run worker:

Recommended drivers:

• database
• redis
• supervisor (production)

⚙️ API

The package exposes a simple CRUD API for managing email mappings. Routes are published under the configured API prefix (default: /api) and are protected by middleware defined in config/mail-mapper.php.

Default endpoints (prefix may include version if configured):

• GET /email-mappings — List mappings. Supports ?per_page= pagination.
• GET /email-mappings/{id} — Get a single mapping.
• POST /email-mappings — Create mapping (returns 201).
• PUT /email-mappings/{id} — Update mapping.
• DELETE /email-mappings/{id} — Delete mapping.

Authentication & Authorization:

• Routes are protected by the middleware defined in config('mail-mapper.api.middleware') (default ['api','auth:api']).
• The package provides a default EmailMappingPolicy (registered by the service provider). Host applications should register permissions (for example email-mapping-configure) or override the policy to customize access control.

Example: Create mapping (cURL)

Response example (201 Created):

Notes:

• The list endpoint supports ?per_page=; the default and maximum values are configurable via config('mail-mapper.api.per_page') and config('mail-mapper.api.max_per_page').

• The package includes an OpenAPI 3 specification at the project root: openapi.yaml.

• To import into Postman: open Postman -> Import -> File -> select openapi.yaml.

• Protect the endpoints using your preferred auth middleware (Sanctum, Passport, or auth:api) by publishing and editing config/mail-mapper.php.
• Consider applying rate-limiting middleware (throttle) in your host application for public APIs.

🧰 Troubleshooting

🧾 Summary

Mail Mapper is a standalone Laravel package that provides a dynamic, database-driven email notification system for modular applications. It enables module, menu, and task-based email routing without hardcoding recipient addresses in application code.

Built for enterprise-scale systems, Mail Mapper allows administrators to manage email recipients and content from the UI, while developers trigger notifications using a simple trait or helper. The package supports queued delivery, customizable HTML templates, and a raw SMTP fallback to ensure reliable email sending across different mail servers.