hook_civicrm_alterMailStore¶

Summary¶

Add or modify email storage drivers (IMAP, POP3, etc).

Description¶

The CiviCRM MailStore or MailSettings layer is used for importing email messages with various sources/settings and protocols (IMAP, POP3, Maildir, etc). There is a built-in list with a handful of drivers (CRM_Mailing_MailStore_Imap, etc).

This hook allows one to manipulate those drivers.

Availability¶

CiviCRM 5.32+

Definition¶

hook_civicrm_alterMailStore(&$mailSettings)

Parameters¶

&$mailSettings: array, a specific record from civicrm_mail_settings. Properties include:
- Pass-through properties, which match civicrm_mail_settings: server, username, password, etc.
- Special properties:
  - protocol: string, the symbolic name of the protocol
  - auth: string, for some protocols, the auth may specify an authentication mechanism
  - factory: callable, a function which generates the MailStore class

Returns¶

null

Example: Add a new protocol FIZZBUZZ¶

Register FIZZBUZZ as a value in the OptionGroup mail_protocol.
Create a driver class (eg CRM_Mailing_MailStore_FizzBuzz extends CRM_Mailing_MailStore)

Use the hook to activate the class:

function hook_civicrm_alterMailStore(&$mailSettings) {
  if ($mailSettings['protocol'] === 'FIZZBUZZ') {
    $mailSettings['factory'] = function ($mailSettings) {
      return new CRM_Mailing_MailStore_FizzBuzz(...);
    };
  }
}

Example: Supplement the IMAP protocol with a dynamic XOAuth2¶

In this example, we replace the password property with a dynamically-generated authentication token.

function hook_civicrm_alterMailStore(&$mailSettings) {
  if (...oauth is relevant...) {
    $mailSettings['auth'] = 'XOAuth2';
    $mailSettings['password'] = $myOauthSystem->getFreshToken(...);
  }
}