PHPackages                             horstoeko/zugferdmail - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. horstoeko/zugferdmail

ActivePackage[Mail & Notifications](/categories/mail)

horstoeko/zugferdmail
=====================

A library

v1.0.1(4mo ago)858MITPHPPHP >=7.4CI passing

Since Oct 2Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/horstoeko/zugferdmail)[ Packagist](https://packagist.org/packages/horstoeko/zugferdmail)[ Docs](https://github.com/horstoeko/zugferdmail)[ RSS](/packages/horstoeko-zugferdmail/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (17)Versions (10)Used By (0)

IMAP/POP3-Watcher for E-Documents
=================================

[](#imappop3-watcher-for-e-documents)

[![Latest Stable Version](https://camo.githubusercontent.com/1fa9127382f2afef26b76bf27be03908f113ec1d8ab84beffe81cbd28cab1b15/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f686f7273746f656b6f2f7a7567666572646d61696c2e7376673f7374796c653d706c6173746963)](https://packagist.org/packages/horstoeko/zugferdmail)[![PHP version](https://camo.githubusercontent.com/5a0d06cf3219b7dc7d57622dcf8feb30d95c6632884f9934ed06911b3e6853a9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f686f7273746f656b6f2f7a7567666572646d61696c2e7376673f7374796c653d706c6173746963)](https://packagist.org/packages/horstoeko/zugferdmail)[![License](https://camo.githubusercontent.com/3e8325f43b3f0b4dabfbfa528f9d10361da0c9fb60bf37cd3abda99807adff60/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f686f7273746f656b6f2f7a7567666572646d61696c2e7376673f7374796c653d706c6173746963)](https://packagist.org/packages/horstoeko/zugferdmail)

[![Build Status](https://github.com/horstoeko/zugferdmail/actions/workflows/build.ci.yml/badge.svg)](https://github.com/horstoeko/zugferdmail/actions/workflows/build.ci.yml)[![Release Status](https://github.com/horstoeko/zugferdmail/actions/workflows/build.release.yml/badge.svg)](https://github.com/horstoeko/zugferdmail/actions/workflows/build.release.yml)

Table of Contents
-----------------

[](#table-of-contents)

- [IMAP/POP3-Watcher for E-Documents](#imappop3-watcher-for-e-documents)
    - [Table of Contents](#table-of-contents)
    - [Note](#note)
    - [License](#license)
    - [Overview](#overview)
    - [Dependencies](#dependencies)
    - [Installation](#installation)
    - [Usage](#usage)
        - [Configuration](#configuration)
        - [Check mail accounts for matching mails:](#check-mail-accounts-for-matching-mails)
        - [Predefined handlers](#predefined-handlers)
        - [Implement your own handler](#implement-your-own-handler)
        - [A small example](#a-small-example)
        - [Console](#console)
            - [Start monitoring a mailbox](#start-monitoring-a-mailbox)

Note
----

[](#note)

Caution

This library is currently still considered experimental and should therefore be used with caution. I would be happy for an issue to be posted if bugs are found.

License
-------

[](#license)

The code in this project is provided under the [MIT](https://opensource.org/licenses/MIT) license.

Overview
--------

[](#overview)

With this library it is possible to monitor mail accounts (IMAP and POP3) and to check and process incoming electronic invoice documents (ZUGFeRD PDF and XML).

Dependencies
------------

[](#dependencies)

This package makes use of

- [horstoeko/zugferd](https://github.com/horstoeko/zugferd)
- [horstoeko/zugferdublbridge](https://github.com/horstoeko/zugferdublbridge)
- [Webklex/php-imap](https://github.com/Webklex/php-imap)

Installation
------------

[](#installation)

There is one recommended way to install `horstoeko/zugferdmail` via [Composer](https://getcomposer.org/):

```
composer require horstoeko/zugferdmail
```

Usage
-----

[](#usage)

For detailed eplanation you may have a look in the [examples](https://github.com/horstoeko/zugferdmail/tree/master/examples) of this package and the documentation attached to every release.

First, it is necessary to configure the library so that it is aware of the mail accounts to be checked. For IMAP accounts, the folders to be monitored must also be defined. In addition, any actions (handlers) can be defined for each mail account.

### Configuration

[](#configuration)

First you need to create a configuration instance:

```
$config = new ZugferdMailConfig();
```

The mail accounts to be monitored must then be defined. You can also specify the folders and mimetypes to be checked:

```
$account1 = $config->addAccount('demo', '192.168.1.1', 993, 'imap', 'ssl', false, 'demouser', 'demopassword');
$account1->addFolderToWatch('INBOX');
$account1->addFolderToWatch('somefolder/somesubfolder');
$account1->addMmimeTypeToWatch('application/pdf');
$account1->addMmimeTypeToWatch('text/xml');
```

Last but not least, the actions (handlers) to be performed are specified for each mail account, which are executed when a ZUGFeRD or XML document is found. Some of these handlers are already available, but you can also define your own actions:

```
$account1->addHandler(new ZugferdMailHandlerMoveMessage('Invoice/Incoming'));
$account1->addHandler(new ZugferdMailHandlerSaveToFile('/tmp', 'invoice.att'));
```

If you wanna use a handler in the case when no valid document was found you can use

```
$account1->addHandlerNoDocumentFound(new SomeHandler())
```

You can also define callbacks to call when a document was found. If such a callback function returns the value false, then all remaining callback functions are not called:

```
$account1->addCallback(function(ZugferdMailAccount $account, Folder $folder, Message $message, Attachment $attachment, ZugferdDocumentReader $document, int $recognitionType) {
    $document->getDocumentInformation($documentno, $documenttypecode, $documentdate, $invoiceCurrency, $taxCurrency, $documentname, $documentlanguage, $effectiveSpecifiedPeriod);
    echo "Document found ... " . PHP_EOL;
    echo "Document No. ..... " . $documentno . PHP_EOL;
});
```

If you wanna use a callback in the case when no valid document was found you can use

```
$account1->addCallbackNoDocumentFound(function(ZugferdMailAccount $account, Folder $folder, Message $message, Attachment $attachment) {
    // Do something when no document was found
});
```

Please note that the callbacks are neither loaded from a configuration file nor saved in one.

### Check mail accounts for matching mails:

[](#check-mail-accounts-for-matching-mails)

To perform the actual handling of all mail accounts, instantiate the class `ZugferdMailReader`, to which the configuration is passed. The monitoring is started by calling the method `checkAllAccounts`

```
$reader = new ZugferdMailReader($config);
$reader->checkAllAccounts();
```

### Predefined handlers

[](#predefined-handlers)

ClassDescriptionZugferdMailHandlerNull*Does not perform any operations*ZugferdMailHandlerCli*Displays brief information about the e-invoice document found on the console*ZugferdMailHandlerCopyMessage*Copies the message to another (different) directory*ZugferdMailHandlerMoveMessage*Moves the message to another (different) directory*ZugferdMailHandlerDeleteMessage*Deletes the message*ZugferdMailHandlerMarkSeenMessage*Marks the message as seen*ZugferdMailHandlerMarkUnseenMessage*Marks the message as unseen*ZugferdMailHandlerSaveToFile*Saves the E-Document to a specified directory, optionally with a different filename*### Implement your own handler

[](#implement-your-own-handler)

It is quite easy to implement your own action (handler). To do this, define your own class which extends a class from `ZugferdMailHandlerAbstract`. This abstract class defines a single method `handleDocument`, which is passed information about the folder, message, attachment and the e-invoice document:

```
public function handleDocument(
    ZugferdMailAccount $account,
    Folder $folder,
    Message $message,
    Attachment $attachment,
    ?ZugferdDocumentReader $document,
    ?int $recognitionType
);
```

The `$document` and `$recognitionType` can be null in the case when no valid attachment was found.

An example:

```
use horstoeko\zugferd\ZugferdDocumentReader;
use horstoeko\zugferdmail\config\ZugferdMailAccount;
use Webklex\PHPIMAP\Attachment;
use Webklex\PHPIMAP\Folder;
use Webklex\PHPIMAP\Message;

class MyOwnHandler extends ZugferdMailHandlerAbstract
{
    public function handleDocument(
        ZugferdMailAccount $account,
        Folder $folder,
        Message $message,
        Attachment $attachment,
        ?ZugferdDocumentReader $document,
        ?int $recognitionType)
    {
        // Do some stuff
    }
}
```

The parameter $recognitionType is one of the constants from `ZugferdMailReaderRecognitionType`

NameVakueDescriptionZFMAIL\_RECOGNITION\_TYPE\_PDF\_CII0The document was recognized from a ZUGFeRD/Factur-X PDF attachmentZFMAIL\_RECOGNITION\_TYPE\_XML\_CII1The document was recognized from a ZUGFeRD/Factur-X XML attachmentZFMAIL\_RECOGNITION\_TYPE\_XML\_UBL2The document was recognized from a ZUGFeRD/Factur-X XML attachment (in UBL-Syntax)### A small example

[](#a-small-example)

A possible implementation could look like this, for example:

```
use Webklex\PHPIMAP\Folder;
use Webklex\PHPIMAP\Message;
use Webklex\PHPIMAP\Attachment;
use horstoeko\zugferd\ZugferdDocumentReader;
use horstoeko\zugferdmail\ZugferdMailReader;
use horstoeko\zugferdmail\config\ZugferdMailConfig;
use horstoeko\zugferdmail\config\ZugferdMailAccount;
use horstoeko\zugferdmail\handlers\ZugferdMailHandlerSaveToFile;

require dirname(__FILE__) . "/../vendor/autoload.php";

$config = new ZugferdMailConfig();

$account1 = $config->addAccount('de', '127.0.0.1', 993, 'imap', 'ssl', false, 'demouser', 'demopassword');
$account1->addFolderToWatch('Accounts/invoice@mydomain.com');
$account1->addMimeTypeToWatch('application/pdf');
$account1->addMimeTypeToWatch('text/xml');
$account1->addHandler(new ZugferdMailHandlerSaveToFile('/tmp', 'file.xml'));
$account1->addCallback(function(ZugferdMailAccount $account, Folder $folder, Message $message, Attachment $attachment, ZugferdDocumentReader $document, int $recognitionType) {
    $document->getDocumentInformation($documentno, $documenttypecode, $documentdate, $invoiceCurrency, $taxCurrency, $documentname, $documentlanguage, $effectiveSpecifiedPeriod);
    // Some business logic here...
});

$account2 = $config->addAccount('de', '172.10.10.10', 993, 'imap', 'ssl', false, 'demouser', 'demopassword');
$account2->addFolderToWatch('Accounts/invoice@otheromain.com');
$account2->addMimeTypeToWatch('application/pdf');
$account2->addMimeTypeToWatch('text/xml');
$account1->addCallback(function(ZugferdMailAccount $account, Folder $folder, Message $message, Attachment $attachment, ZugferdDocumentReader $document, int $recognitionType) {
    $document->getDocumentInformation($documentno, $documenttypecode, $documentdate, $invoiceCurrency, $taxCurrency, $documentname, $documentlanguage, $effectiveSpecifiedPeriod);
    // Some other business logic here...
});

$reader = new ZugferdMailReader($config);
$reader->checkAllAccounts();
```

### Console

[](#console)

This library also includes a console application with which it is possible to carry out corresponding operations via shell. To get an overview of the existing commands from the “zfmail” namespace, use:

```
./vendor/bin/ZugferdMailConsole list
```

#### Start monitoring a mailbox

[](#start-monitoring-a-mailbox)

The command `zfmail:processmailboxfolders` is available for monitoring a mailbox via shell:

```
./vendor/bin/ZugferdMailConsole zfmail:processmailboxfolders [options]
```

This has the following parameters:

ParameterDescriptionDefaultMultiplehostThe IP or hostname❌portThe port on the host993❌protocolThe protocol to useimap❌encryptionThe encryption method to usessl❌validateCertIf given the SSL certificates will be validatedfalse❌usernameThe username to use for login❌passwordThe password to use for login❌authenticationThe authentication method to use❌timeoutThe connection timeout30❌folderA folder to look into✔️mimetypeAn attachment mimetype to check✔️handlerA handler to use✔️enableublsupportIf given the application will check for UBL syntax toofalse❌enablesymfonyvalidationIf given the application will validate the XML using symfony validator against the yaml definitionsfalse❌enablexsdvalidationIf given the application will validate the XML against the XSD definitionsfalse❌enablekositvalidationIf given the application will validate the XML using the KosIT validator (JAVA required)false❌enableunseenonlyIf given only unseen message are processedfalse❌Example usage

```
./vendor/bin/ZugferdMailConsole zfmail:processmailboxfolders \
  --host 127.0.0.1 \
  --port 993 \
  --username demouser \
  --password demopassword \
  --folder=INBOX \
  --mimetype=application/pdf \
  --mimetype=text/xml \
  --handler="horstoeko\zugferdmail\handlers\ZugferdMailHandlerCli" \
  --handler="horstoeko\zugferdmail\handlers\ZugferdMailHandlerSaveToFile,/tmp" \
  --enableublsupport
```

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance80

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 70% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~64 days

Recently: every ~110 days

Total

8

Last Release

139d ago

Major Versions

v0.0.6 → v1.0.02024-11-22

PHP version history (3 changes)v0.0.1PHP ^7.3|^7.4|^8

v1.0.0PHP >=7.3

v1.0.1PHP >=7.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/24de09032b9a378d782bb7eac3f60914f64967e5a68d51527439dcf7c51711ba?d=identicon)[horstoeko](/maintainers/horstoeko)

---

Top Contributors

[![horstoeko](https://avatars.githubusercontent.com/u/2326713?v=4)](https://github.com/horstoeko "horstoeko (14 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (6 commits)")

---

Tags

electronic-invoiceselectronic-invoicingen16931factur-ximapphpphp7php8pop3xrechnungzugferd

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/horstoeko-zugferdmail/health.svg)

```
[![Health](https://phpackages.com/badges/horstoeko-zugferdmail/health.svg)](https://phpackages.com/packages/horstoeko-zugferdmail)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.7k509.9M17.0k](/packages/laravel-framework)[symfony/mailer

Helps sending emails

1.6k368.1M955](/packages/symfony-mailer)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[kimai/kimai

Kimai - Time Tracking

4.6k7.4k1](/packages/kimai-kimai)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)[directorytree/imapengine

A fully-featured IMAP library -- without the PHP extension

531175.4k4](/packages/directorytree-imapengine)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)