Skip to main content

Developer Resources

The Mailbox module provides several integration points that developers can use to extend its functionality or connect it to other modules within a Qore application.

This section explains how to listen for email events and how to integrate your own resources so they can be coupled directly to emails.

Email Events​

Whenever an email is created or updated, the Mailbox module fires specific events.
These events make it easy for other modules or services to react to incoming or modified emails — for example, to trigger automation, classification, or synchronization logic.

protected $dispatchesEvents = [
    'created' => InboundEmailCreated::class,
    'updated' => InboundEmailUpdated::class,
];

Both events carry the full InboundEmail model as their payload, giving you complete access to all of its related data and relationships.

Example Usage​

You can listen for these events inside your own module’s EventServiceProvider:

use Qore\Mailbox\Events\InboundEmailCreated;
use Qore\Mailbox\Events\InboundEmailUpdated;

protected $listen = [
    InboundEmailCreated::class => [
        \App\Listeners\HandleInboundEmailCreated::class,
    ],
    InboundEmailUpdated::class => [
        \App\Listeners\HandleInboundEmailUpdated::class,
    ],
];

This allows your module to respond to email activity in real time — for instance,
to create linked records, trigger notifications, or perform content analysis.

Coupling Custom Resources to Emails​

The Mailbox module was designed to integrate seamlessly with other Qore resources.
If you have a resource that includes a belongsTo relationship with the Organization model,
it will automatically become available for coupling in the Mailbox module settings.

This means you can easily allow your custom resource to be linked to specific emails —
no additional configuration or code is required.

Example​

Imagine you have an Invoice resource that relates to an organization:

public function organization(): BelongsTo
{
    return $this->belongsTo(Organization::class);
}

Once your module is enabled, the Invoice resource will automatically appear in the
Attachable Resources dropdown within the Mailbox module settings.

After enabling it there, users will be able to:

  • Couple emails directly to invoice records from within the Mailbox module.
  • View all related emails directly from the detail page of the invoice resource.
  • Automatically detect and link emails based on invoice identifiers (e.g. serial numbers).

Automatic Serial Number Matching​

If your resource implements or uses Qore serial numbers,
the Mailbox module will automatically search for any occurrences of these serial numbers in incoming emails.

When a match is found:

  1. The email is automatically linked to the corresponding resource instance.
  2. The coupling will immediately appear in both the email’s detail view and the related resource’s page.

This process happens transparently during email import or update events, requiring no developer intervention.

Implementing New Mail Drivers​

The Mailbox module has been designed with extensibility in mind.
If a new email provider needs to be supported in the future, the foundation for additional mail drivers is already in place.

Drivers can be found inside the Drivers directory of the module.

  • AbstractMailboxDriver
    This abstract class defines the base contract and required functionality that all mail drivers must implement.
    It contains shared logic for handling mailbox connections, synchronization, and email import.

  • GraphDriver
    A complete implementation example of a mail driver using the Microsoft Graph API.
    This serves as a reference for how new drivers should extend and implement AbstractMailboxDriver.

To register a new driver so it can be selected when creating a mailbox,
add it to the MailboxDriverManager, where all supported drivers are registered.

This flexible system makes it straightforward to extend Qore’s Mailbox module with new providers such as Gmail, IMAP, or other APIs, without modifying the core module itself.