Skip to content



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


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.


CiviCRM 5.32+




  • &$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


  • 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(...);