README

A Mautic plugin that automatically checks email deliverability status for contacts using an external API service.

Features

Automatic Email Validation: Validates email addresses when contacts are created or updated
Real-time API Integration: Connects to your email deliverability API service
Custom Field Integration: Stores deliverability status in a custom contact field
Configurable: Easy setup through Mautic's configuration interface
Prevents Duplicates: Smart processing to avoid checking the same email multiple times

Requirements

Mautic 4.x or 5.x
PHP 7.4 or higher
Access to an email deliverability checking API

Installation

Method 1: Manual Installation

Download the plugin or clone this repository:

   cd /path/to/mautic/plugins
   git clone https://github.com/mailexpert/EmailDeliverabilityBundle.git

Set correct permissions:

   chown -R www-data:www-data EmailDeliverabilityBundle

Install the plugin:

   cd /path/to/mautic
   php bin/console mautic:plugins:install
   php bin/console cache:clear

Method 2: Using Composer

cd /path/to/mautic
composer require mailexpert/email-deliverability-bundle
php bin/console mautic:plugins:install
php bin/console cache:clear

Configuration

1. Configure API Settings

Go to Settings → Plugins
Find Email Deliverability Plugin and click on it
Click the gear/settings icon to configure
Enable the plugin by toggling "Published" to ON
Configure the API settings:
- API URL: https://emaildelivery.space/me/checkemail (default)
- API Key: Get your API key from https://emaildelivery.space/ or send an email to apikey@emaildelivery.space
Click Save & Close

2. Clear Cache

php bin/console cache:clear

Usage

Once installed and configured, the plugin works automatically:

Custom Field Creation: The plugin automatically creates a deliverability_status custom field on first use if it doesn't exist
New Contacts: When a new contact is created (via form, API, or manual entry), the plugin automatically checks the email deliverability
Updated Contacts: When a contact's email is updated, the plugin re-validates if the status is empty or "not_checked"
Status Field: The deliverability status is stored in the deliverability_status custom field

Deliverability Statuses

The plugin stores various statuses returned by your API, such as:

deliverable - Email is valid and deliverable
soft bounce - Email has received Soft Bounce response
hard bounce - Email has received Hard Bounce response
sent - Email is used to send an email (but no additional info for the outcome)
unknown - Unable to determine status
not_checked - Email hasn't been checked yet

Mautic UI

API Integration

The plugin integrates with the Email Deliverability API service at https://emaildelivery.space/.

Getting Your API Key

Visit https://emaildelivery.space/
Sign up or log in to your account
Navigate to your API settings
Copy your API key
Add it to the plugin configuration in Mautic (Settings → Plugins → Email Deliverability Plugin)

Alternatively, send an email to apikey@emaildelivery.space

Default API Endpoint

The plugin uses https://emaildelivery.space/me/checkemail as the default API endpoint. This can be customized in the plugin configuration if needed.

API Request/Response

The plugin sends email validation requests to the API and processes the response to determine deliverability status.

Troubleshooting

Plugin Not Working

Check if plugin is enabled:
- Go to Settings → Plugins
- Ensure "Email Deliverability Plugin" is Published
Verify custom field exists:
- Go to Settings → Custom Fields
- The plugin should have automatically created a field with alias deliverability_status
- If not, the plugin will create it on the first contact save
Check logs:

   tail -f /var/www/html/var/logs/mautic_prod.log

Enable debug logging (for development):

   # Check debug logs
   cat /tmp/deliverability_debug.log

API Connection Issues

Verify API key is correct:
- Go to Settings → Plugins → Email Deliverability Plugin
- Ensure your API key from https://emaildelivery.space/ is entered correctly
Test API endpoint manually:

   curl -X GET https://emaildelivery.space/me/checkemail?email=inboxfull1@gmail.com \
     -H "Content-Type: application/json" \
     -d '{"api_key":"your-key"}'

Check API credentials in plugin configuration
Verify network connectivity from your Mautic server to emaildelivery.space

Clear Cache

If changes aren't taking effect:

php bin/console cache:clear
rm -rf var/cache/*

Development

File Structure

EmailDeliverabilityBundle/
├── Config/
│   └── config.php              # Plugin configuration
├── EventListener/
│   └── ContactSubscriber.php   # Event listener for contact changes
├── Helper/
│   └── DeliverabilityChecker.php  # API integration helper
├── Integration/
│   └── EmailDeliverabilityIntegration.php  # Integration class
└── EmailDeliverabilityBundle.php  # Main bundle class

Adding Debug Logging

For debugging, you can add logging to track plugin behavior:

file_put_contents('/tmp/deliverability_debug.log', 
    date('Y-m-d H:i:s') . " - Your debug message\n", 
    FILE_APPEND
);

Running Tests

cd /path/to/mautic
php bin/phpunit --filter EmailDeliverability

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This plugin is open-source software. Please check the LICENSE file for details.

Support

Issues: Report bugs or request features on GitHub Issues
Documentation: Mautic Plugin Documentation
Community: Mautic Community Forums

Credits

Developed by Mail Xpert

Changelog

Version 1.1

Added automatic email validation on contact creation
Improved error handling and logging
Added support for multiple deliverability statuses
Enhanced API integration

Version 1.0

Initial release
Basic email deliverability checking
Custom field integration

mailexpert / email-deliverability-bundle

Maintainers

Details