molnix/bounced-mail-manager

Check for bounced emails and take action on them.

v2.1.0 2023-12-11 12:51 UTC

Requires

• php: ^7.1|^8.0
• guzzlehttp/guzzle: ^7.0
• nesbot/carbon: ^2.71
• webklex/php-imap: ^5.5

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.27
• phpmailer/phpmailer: ^6.9

MIT

• Vishnu

• email
• bounce
• laravel

README

A package can read IMAP and parse mails to check if they are bounced emails. When used with laravel, can notifiy the original sender.

Installation:

composer require molnix/bounced-mail-manager

Add the custom headers created by the getCustomHeaders method to outgoing mails.

Molnix\BouncedMailManager\Message\Header::getCustomHeaders(
string  $sender, // Sender email to send notificaitons
string  $sentTo, // send to email
string  $subject ='' optional subject
): array

Laravel

Package can be customized with optional env variables

Variable	Description
BOUNCEMAIL_HOST	IMAP host url, default: MAIL_HOST from .env
BOUNCEMAIL_PORT	IMAP port, default: 993
BOUNCEMAIL_USERNAME	IMAP username, default: MAIL_USERNAME from .env
BOUNCEMAIL_PASSWORD	IMAP password, default: MAIL_PASSWORD from .env
BOUNCEMAIL_MAILBOX	Mailox name, default: INBOX
BOUNCEMAIL_DELETE_MODE	False will use read/unread instead of deleting, default: true
BOUNCEMAIL_TYPE	Mailbox type: null. imap,o365 , default: imap
BOUNCEMAIL_OAUTH_CLIENT_ID	Oauth client id , default: null
BOUNCEMAIL_OAUTH_SECRET	Oauth secret , default: null
BOUNCEMAIL_AZURE_TENANT_ID	Azure tenant id if using office 365 , default: null

Configuration

The package will automatically register a service provider. You can publish for further customization.

Tag	Description
config	Configuration
views	Notification email markdown
translations	Bounce reason translations

Optionally publish files if further customization is required.

php  artisan  vendor:publish  --provider="Molnix\BouncedMailManager\BounceManagerServiceProvider"  --tag="config"
php  artisan  vendor:publish  --provider="Molnix\BouncedMailManager\BounceManagerServiceProvider"  --tag="views"
php  artisan  vendor:publish  --provider="Molnix\BouncedMailManager\BounceManagerServiceProvider"  --tag="translations"

Usage

Use Molnix\BouncedMailManager\Traits\BounceMailHeaders trait in Mailable to add headers to outgoing headers.

Option 1: With setup

// PostMail
use BounceMailHeaders;
public function __construct(Comment $comment)
    {
        $this->comment = $comment;
        $this->setupBounceManager();
    }
public function build(){
    $this->subject('Comment added')
                ->markdown('emails.comment')
                ->addBounceManagerHeaders();
}

Option 2: Without setup

// PostMail
use BounceMailHeaders;
public function __construct(Comment $comment, $sender)
    {
        $this->comment = $comment;
        $this->sender = $sender;
    }
public function build(){
    $this->subject('Comment added')
                ->markdown('emails.comment')
                ->addBounceManagerHeaders($this->sender);
}

Add this command to the scheduler.

php artisan bouncemanager:run

PHP

- #### Create instance
```php
use Molnix\BouncedMailManager\BounceManager;
$manager = new BounceManager(
    'imap.example.com', 
    '993', 
    '[e-mail]', 
    'emailpassword', 
    string $mailbox = 'INBOX', 
    array $options = [] // extra optional options
);

or

use Molnix\BouncedMailManager\BounceManager;
use Molnix\BouncedMailManager\Clients\ImapClient;

$manager->setClient(new ImapClient(
    'imap.example.com', 
    '993', 
    '[e-mail]', 
    'emailpassword', 
    string $mailbox = 'INBOX', 
    array $options = [] // extra optional options
));

or Office 365 way

use Molnix\BouncedMailManager\BounceManager;
use Molnix\BouncedMailManager\Clients\O365Client;

$manager = new BounceManager();
$manager->setClient(new O365Client('[e-mail]', $tenant_id, $client_id, $client_secret));

• Change mailbox

$manager->setMailbox('OtherMailbBoxName');

• Set period of days to parse

// Use -1 for all mails.
$manager->setDaysFrom(10); // Since last 10 days

• Set how to handle processed email management. Default is to mark the mail as seen. To use delete after process:

$manager->enableDeleteMode(); // Since last 10 days

• Get data

$manager->toArray(); // Returns simple array of bounces.
$manager->get(); // Returns array of bounces objects.

Setup office 365 mailbox.

The setup needed to be done in two section,

1. Azure web portal
2. Powershell

Azure web portal

1. Register app in azure

1. Setup Permissions, Click on API permissions -> APIs my organization uses tab -> serach Office 365 Exchange Online -> Application permissions -> IMAP.AccessAsApp

1. Grant admin consent by clicking the button

1. Create app secret. Once created, Copy the value as it shows only once.

Powershell

Run these commands in powershell in order one by one. Remember to replace values for $AppId with Application (client) ID, $TenantId with Directory (tenant) ID. These can be found in the app page in azure web. Your email ID with the mailbox email you grant access to.

Install-Module -Name AzureAD
Install-Module -Name ExchangeOnlineManagement


$AppId = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
$TenantId = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Import-module AzureAD
Connect-AzureAd -Tenant $TenantId

($Principal = Get-AzureADServicePrincipal -filter "AppId eq '$AppId'")
$PrincipalId = $Principal.ObjectId


$DisplayName = "Bounce manager IMAP Access"

Import-module ExchangeOnlineManagement
Connect-ExchangeOnline -Organization $TenantId

New-ServicePrincipal -AppId $AppId -ServiceId $PrincipalId -DisplayName $DisplayName

Add-MailboxPermission -User $PrincipalId -AccessRights FullAccess -Identity "Your email ID"

Usage

use Molnix\BouncedMailManager\BounceManager;
use Molnix\BouncedMailManager\Clients\O365;

$manager = new BounceManager();
$manager->setClient(new O365('[e-mail]', $tenant_id, $client_id, $client_secret));
$manager->get();

Made with ❤ in Finland by Molnix and Webbhuset