diff --git a/docs/hooks/hook_civicrm_alterMailingRecipients.md b/docs/hooks/hook_civicrm_alterMailingRecipients.md new file mode 100644 index 0000000000000000000000000000000000000000..36c31eaa07cb16aed9e2f9e058414c11a0c5b263 --- /dev/null +++ b/docs/hooks/hook_civicrm_alterMailingRecipients.md @@ -0,0 +1,49 @@ +# 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') + } + } +``` diff --git a/docs/hooks/list.md b/docs/hooks/list.md index 0f44fff1fa82c3143585a61348ae5e445a6d7eea..adeada6b7925faf9e15874ac9efb125ab5ac7bf6 100644 --- a/docs/hooks/list.md +++ b/docs/hooks/list.md @@ -88,6 +88,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.