molnix/bounced-mail-manager

Check for bounced emails and take action on them.

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

This package is auto-updated.

Last update: 2024-07-11 14:10:50 UTC


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

Configuration

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

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', 
    'wind@example.com', 
    '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', 
    'wind@example.com', 
    '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('wind@example.com', $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

Screenshot from 2023-12-04 17-12-11

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

Screenshot from 2023-12-04 17-20-23

  1. Grant admin consent by clicking the button

Screenshot from 2023-12-04 17-21-44

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

Screenshot from 2023-12-04 17-25-49

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('wind@example.com', $tenant_id, $client_id, $client_secret));
$manager->get();

Made with ❤ in Finland by Molnix and Webbhuset