Skip to content

hook_civicrm_alterMailParams

Summary

This hook is called when an email is being prepared for sending by CiviCRM.

It is also called when downloading or emailing PDF invoices and receipts from the route, civicrm/contribute/invoice from within printPDF() when CRM_Core_BAO_MessageTemplate calls loadTemplate().

Definition

hook_civicrm_alterMailParams(&$params, $context)

Parameters

  • $params - the mailing params array
  • $context - the contexts of the hook call are:
    • "civimail" for when sending an email using CiviMail,
    • "flexmailer" for when sending an email using CiviMail and FlexMailer (e.g. for Mosaico),
    • "singleEmail" for when sending a single email,
    • "messageTemplate" for when sending an email using a message template or generating PDF's.

Details

  • $params array fields include: workflow, from, toName, toEmail, subject, cc, bcc, text, html, returnPath, replyTo, headers (array), attachments (array), and possibly others depending on context.
  • $params array used to include valueName and groupName. These should not be referenced as they will stop working in future upgrades The option groups they referred to are obsolete & will also be phased out. workflow should be checked instead.
  • To alter a System Workflow Template, override the workflow param.
  • To override with a custom workflow template, unset workflow, groupName, and valueName, and set messageTemplateID.
  • If you want to abort the mail from being sent, set the boolean abortMailSend to true in the params array
  • Note that this hook is called twice when sending a message template, once early in the message generation (before tokens are applied, with the context => messageTemplate) and then later from CRM_Utils_Mail::send() with the context => singleEmail.

Adding custom headers to the email

You can add custom headers by appending to $params['headers']. Example:

```php
$params['headers']['X-My-Header'] = 'my header value';
```

The headers key may not exist in the $params array when passed into the hook.

For CiviMail based emails you can also add headers by simply adding a key directly to the $params array, however as CiviMail also supports the above, so it might be safer to use the headers key when adding headers as this is supported across all methods.

Study the source before atttempting to set or unset non-custom headers this way!