CRM-20845: document alterMailingRecipients hook

docs/hooks/hook_civicrm_alterMailingRecipients.md

+# hook_civicrm_alterMailingRecipients
+
+## Summary
+
+This hook is called to allow the user to alter the mailing recipients after they have been constructed.
+
+### Notes
+
+!!! Note
+    This hook is called two times, once at the start and once at the end of mail recipients
+    building, identified by $context as 'pre' or 'post' respectively
+
+## Availability
+
+This hook was first available in CiviCRM 4.7.32
+
+## Definition
+
+```php
+    function hook_civicrm_alterMailingRecipients(&$mailingObject, &$criteria, $context);
+```
+
+## Parameters
+
+-   object `$mailingObject` - reference to CRM_Mailing_DAO_Mailing object
+-   array `$criteria` - the criteria in terms of SQL fragments Array(string $name => CRM_Utils_SQL_Select $criterion) to manipulate mailing recipients
+-   string `$context` - contain 'pre' or 'post' value to indicate when the hook is fired
+
+## Returns
+
+-   null
+
+## Example
+```php
+    function mymodule_civicrm_alterMailingRecipients(&$mailingObject, &$criteria, $context) {
+      // fetch all emails marked is_bulkmail only AND consider only those contacts which are tagged with Volunteer
+      if ($context == 'pre') {
+        // criteria to choose email which are only used for mass mailing
+        $criteria['location_filter'] = CRM_Utils_SQL_Select::fragment()->where("civicrm_email.is_bulkmail = 1");
+        // criteria to choose contacts which are tagged 'Volunteer'
+        $criteria['tag_filter'] = CRM_Utils_SQL_Select::fragment()
+                                  ->join('civicrm_entity_tag', "INNER JOIN civicrm_entity_tag et ON et.entity_id = civicrm_contact.id AND et.entity_table = 'civicrm_contact'")
+                                  ->join('civicrm_tag', "INNER JOIN civicrm_tag t ON t.id = et.tag_id")
+                                  ->where("t.name = 'Volunteer'");
+        // criteria to change order by to use is_bulkmail
+        $criteria['order_by'] = CRM_Utils_SQL_Select::fragment()->orderBy('civicrm_email.is_bulkmail')
+      }
+    }
+```

docs/hooks/list.md

@@ -86,6 +86,7 @@ This is an overview list of all available hooks, listed by category.
 * **[hook_civicrm_alterMailContent](/hooks/hook_civicrm_alterMailContent.md)** - called after getting the content of the mail and before tokenizing it.
 * **[hook_civicrm_alterMailer](/hooks/hook_civicrm_alterMailer.md)** - called when CiviCRM prepares an email driver class to handle outbound message delivery.
 * **[hook_civicrm_alterMailParams](/hooks/hook_civicrm_alterMailParams.md)** - called when an email is about to be sent by CiviCRM.
+* **[hook_civicrm_alterMailingRecipients](/hooks/hook_civicrm_alterMailingRecipients.md)** - called twice, once before and once after constructing mail recipients.
 * **[hook_civicrm_emailProcessor](/hooks/hook_civicrm_emailProcessor.md)** - called after *each* email has been processed by the script `bin/EmailProcessor.php`.
 * **[hook_civicrm_emailProcessorContact](/hooks/hook_civicrm_emailProcessorContact.md)** - called by the Email Processor when deciding to which contact and activity will be attached.
 * **[hook_civicrm_mailingGroups](/hooks/hook_civicrm_mailingGroups.md)** - called when composing a mailing allowing you to include or exclude other groups as needed.