3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
15 * @copyright CiviCRM LLC https://civicrm.org/licensing
17 class CRM_Utils_Mail
{
20 * Create a new mailer to send any mail from the application.
22 * Note: The mailer is opened in persistent mode.
24 * Note: You probably don't want to call this directly. Get a reference
25 * to the mailer through the container.
29 * @throws CRM_Core_Exception
31 public static function createMailer() {
32 $mailingInfo = Civi
::settings()->get('mailing_backend');
35 if ($mailingInfo['outBound_option'] == CRM_Mailing_Config
::OUTBOUND_OPTION_REDIRECT_TO_DB ||
36 (defined('CIVICRM_MAILER_SPOOL') && CIVICRM_MAILER_SPOOL
)
38 $mailer = self
::_createMailer('CRM_Mailing_BAO_Spool', []);
40 elseif ($mailingInfo['outBound_option'] == CRM_Mailing_Config
::OUTBOUND_OPTION_SMTP
) {
41 if ($mailingInfo['smtpServer'] == '' ||
!$mailingInfo['smtpServer']) {
42 Civi
::log()->error(ts('There is no valid smtp server setting. Click <a href=\'%1\'>Administer >> System Setting >> Outbound Email</a> to set the SMTP Server.', [1 => CRM_Utils_System
::url('civicrm/admin/setting/smtp', 'reset=1')]));
43 throw new CRM_Core_Exception(ts('There is no valid smtp server setting. Click <a href=\'%1\'>Administer >> System Setting >> Outbound Email</a> to set the SMTP Server.', [1 => CRM_Utils_System
::url('civicrm/admin/setting/smtp', 'reset=1')]));
46 $params['host'] = $mailingInfo['smtpServer'] ?
$mailingInfo['smtpServer'] : 'localhost';
47 $params['port'] = $mailingInfo['smtpPort'] ?
$mailingInfo['smtpPort'] : 25;
49 if ($mailingInfo['smtpAuth']) {
50 $params['username'] = $mailingInfo['smtpUsername'];
51 $params['password'] = \Civi
::service('crypto.token')->decrypt($mailingInfo['smtpPassword']);
52 $params['auth'] = TRUE;
55 $params['auth'] = FALSE;
59 * Set the localhost value, CRM-3153
60 * Use the host name of the web server, falling back to the base URL
61 * (eg when using the PHP CLI), and then falling back to localhost.
63 $params['localhost'] = CRM_Utils_Array
::value(
66 CRM_Utils_Array
::value(
68 parse_url(CIVICRM_UF_BASEURL
),
73 // also set the timeout value, lets set it to 30 seconds
75 $params['timeout'] = 30;
78 $params['persist'] = TRUE;
80 $mailer = self
::_createMailer('smtp', $params);
82 elseif ($mailingInfo['outBound_option'] == CRM_Mailing_Config
::OUTBOUND_OPTION_SENDMAIL
) {
83 if ($mailingInfo['sendmail_path'] == '' ||
84 !$mailingInfo['sendmail_path']
86 Civi
::log()->error(ts('There is no valid sendmail path setting. Click <a href=\'%1\'>Administer >> System Setting >> Outbound Email</a> to set the sendmail server.', [1 => CRM_Utils_System
::url('civicrm/admin/setting/smtp', 'reset=1')]));
87 throw new CRM_Core_Exception(ts('There is no valid sendmail path setting. Click <a href=\'%1\'>Administer >> System Setting >> Outbound Email</a> to set the sendmail server.', [1 => CRM_Utils_System
::url('civicrm/admin/setting/smtp', 'reset=1')]));
89 $params['sendmail_path'] = $mailingInfo['sendmail_path'];
90 $params['sendmail_args'] = $mailingInfo['sendmail_args'];
92 $mailer = self
::_createMailer('sendmail', $params);
94 elseif ($mailingInfo['outBound_option'] == CRM_Mailing_Config
::OUTBOUND_OPTION_MAIL
) {
95 $mailer = self
::_createMailer('mail', []);
97 elseif ($mailingInfo['outBound_option'] == CRM_Mailing_Config
::OUTBOUND_OPTION_MOCK
) {
98 $mailer = self
::_createMailer('mock', $mailingInfo);
100 elseif ($mailingInfo['outBound_option'] == CRM_Mailing_Config
::OUTBOUND_OPTION_DISABLED
) {
101 Civi
::log()->info(ts('Outbound mail has been disabled. Click <a href=\'%1\'>Administer >> System Setting >> Outbound Email</a> to set the OutBound Email.', [1 => CRM_Utils_System
::url('civicrm/admin/setting/smtp', 'reset=1')]));
102 CRM_Core_Error
::statusBounce(ts('Outbound mail has been disabled. Click <a href=\'%1\'>Administer >> System Setting >> Outbound Email</a> to set the OutBound Email.', [1 => CRM_Utils_System
::url('civicrm/admin/setting/smtp', 'reset=1')]));
105 Civi
::log()->error(ts('There is no valid SMTP server Setting Or SendMail path setting. Click <a href=\'%1\'>Administer >> System Setting >> Outbound Email</a> to set the OutBound Email.', [1 => CRM_Utils_System
::url('civicrm/admin/setting/smtp', 'reset=1')]));
106 CRM_Core_Error
::debug_var('mailing_info', $mailingInfo);
107 CRM_Core_Error
::statusBounce(ts('There is no valid SMTP server Setting Or sendMail path setting. Click <a href=\'%1\'>Administer >> System Setting >> Outbound Email</a> to set the OutBound Email.', [1 => CRM_Utils_System
::url('civicrm/admin/setting/smtp', 'reset=1')]));
113 * Create a new instance of a PEAR Mail driver.
115 * @param string $driver
116 * 'CRM_Mailing_BAO_Spool' or a name suitable for Mail::factory().
117 * @param array $params
119 * More specifically, a class which implements the "send()" function
121 public static function _createMailer($driver, $params) {
122 if ($driver == 'CRM_Mailing_BAO_Spool') {
123 $mailer = new CRM_Mailing_BAO_Spool($params);
126 $mailer = Mail
::factory($driver, $params);
129 // Previously, CiviCRM bundled patches to change the behavior of 3 specific drivers. Use wrapper/filters to avoid patching.
130 $mailer = new CRM_Utils_Mail_FilteredPearMailer($driver, $params, $mailer);
131 if (in_array($driver, ['smtp', 'mail', 'sendmail'])) {
132 $mailer->addFilter('2000_log', ['CRM_Utils_Mail_Logger', 'filter']);
133 $mailer->addFilter('2100_validate', function ($mailer, &$recipients, &$headers, &$body) {
134 if (!is_array($headers)) {
135 return PEAR
::raiseError('$headers must be an array');
139 CRM_Utils_Hook
::alterMailer($mailer, $driver, $params);
144 * Wrapper function to send mail in CiviCRM. Hooks are called from this function. The input parameter
145 * is an associateive array which holds the values of field needed to send an email. These are:
147 * from : complete from envelope
148 * toName : name of person to send email
149 * toEmail : email address to send to
150 * cc : email addresses to cc
151 * bcc : email addresses to bcc
152 * subject : subject of the email
153 * text : text of the message
154 * html : html version of the message
155 * replyTo : reply-to header in the email
156 * returnpath : email address for bounces to be sent to
157 * messageId : Message ID for this email mesage
158 * attachments: an associative array of
159 * fullPath : complete pathname to the file
160 * mime_type: mime type of the attachment
161 * cleanName: the user friendly name of the attachmment
162 * contactId : contact id to send the email to (optional)
164 * @param array $params
168 * TRUE if a mail was sent, else FALSE.
170 public static function send(array &$params): bool {
171 $defaultReturnPath = CRM_Core_BAO_MailSettings
::defaultReturnPath();
172 $includeMessageId = CRM_Core_BAO_MailSettings
::includeMessageId();
173 $emailDomain = CRM_Core_BAO_MailSettings
::defaultDomain();
174 $from = $params['from'] ??
NULL;
175 if (!$defaultReturnPath) {
176 $defaultReturnPath = self
::pluckEmailFromHeader($from);
179 // first call the mail alter hook
180 CRM_Utils_Hook
::alterMailParams($params, 'singleEmail');
182 // check if any module has aborted mail sending
183 if (!empty($params['abortMailSend']) ||
empty($params['toEmail'])) {
187 $htmlMessage = $params['html'] ??
FALSE;
188 if (trim(CRM_Utils_String
::htmlToText((string) $htmlMessage)) === '') {
189 $htmlMessage = FALSE;
191 $attachments = $params['attachments'] ??
NULL;
192 if (!empty($params['text'])) {
193 $textMessage = $params['text'];
196 $textMessage = CRM_Utils_String
::htmlToText($htmlMessage);
197 // Render the & entities in text mode, so that the links work.
198 // This is copied from the Action Schedule send code.
199 $textMessage = str_replace('&', '&', $textMessage);
203 // CRM-10699 support custom email headers
204 if (!empty($params['headers'])) {
205 $headers = array_merge($headers, $params['headers']);
207 $headers['From'] = $params['from'];
208 $headers['To'] = self
::formatRFC822Email(
209 CRM_Utils_Array
::value('toName', $params),
210 CRM_Utils_Array
::value('toEmail', $params),
214 // On some servers mail() fails when 'Cc' or 'Bcc' headers are defined but empty.
215 foreach (['Cc', 'Bcc'] as $optionalHeader) {
216 $headers[$optionalHeader] = $params[strtolower($optionalHeader)] ??
NULL;
217 if (empty($headers[$optionalHeader])) {
218 unset($headers[$optionalHeader]);
222 $headers['Subject'] = $params['subject'] ??
NULL;
223 $headers['Content-Type'] = $htmlMessage ?
'multipart/mixed; charset=utf-8' : 'text/plain; charset=utf-8';
224 $headers['Content-Disposition'] = 'inline';
225 $headers['Content-Transfer-Encoding'] = '8bit';
226 $headers['Return-Path'] = CRM_Utils_Array
::value('returnPath', $params, $defaultReturnPath);
228 // CRM-11295: Omit reply-to headers if empty; this avoids issues with overzealous mailservers
229 $replyTo = CRM_Utils_Array
::value('replyTo', $params, CRM_Utils_Array
::value('from', $params));
231 if (!empty($replyTo)) {
232 $headers['Reply-To'] = $replyTo;
234 $headers['Date'] = date('r');
235 if ($includeMessageId) {
236 $headers['Message-ID'] = $params['messageId'] ??
'<' . uniqid('civicrm_', TRUE) . "@$emailDomain>";
238 if (!empty($params['autoSubmitted'])) {
239 $headers['Auto-Submitted'] = "Auto-Generated";
242 // make sure we has to have space, CRM-6977
243 foreach (['From', 'To', 'Cc', 'Bcc', 'Reply-To', 'Return-Path'] as $fld) {
244 if (isset($headers[$fld])) {
245 $headers[$fld] = str_replace('"<', '" <', $headers[$fld]);
249 // quote FROM, if comma is detected AND is not already quoted. CRM-7053
250 if (strpos($headers['From'], ',') !== FALSE) {
251 $from = explode(' <', $headers['From']);
252 $headers['From'] = self
::formatRFC822Email(
254 substr(trim($from[1]), 0, -1),
259 require_once 'Mail/mime.php';
260 $msg = new Mail_mime("\n");
262 $msg->setTxtBody($textMessage);
266 $msg->setHTMLBody($htmlMessage);
269 if (!empty($attachments)) {
270 foreach ($attachments as $attach) {
273 $attach['mime_type'],
274 $attach['cleanName'],
278 (isset($attach['charset']) ?
$attach['charset'] : '')
283 $message = self
::setMimeParams($msg);
284 $headers = $msg->headers($headers);
286 $to = [$params['toEmail']];
287 $mailer = \Civi
::service('pear_mail');
289 // CRM-3795, CRM-7355, CRM-7557, CRM-9058, CRM-9887, CRM-12883, CRM-19173 and others ...
290 // The PEAR library requires different parameters based on the mailer used:
291 // * Mail_mail requires the Cc/Bcc recipients listed ONLY in the $headers variable
292 // * All other mailers require that all be recipients be listed in the $to array AND that
293 // the Bcc must not be present in $header as otherwise it will be shown to all recipients
294 // ref: https://pear.php.net/bugs/bug.php?id=8047, full thread and answer [2011-04-19 20:48 UTC]
295 // TODO: Refactor this quirk-handler as another filter in FilteredPearMailer. But that would merit review of impact on universe.
296 $driver = ($mailer instanceof CRM_Utils_Mail_FilteredPearMailer
) ?
$mailer->getDriver() : NULL;
297 $isPhpMail = (get_class($mailer) === "Mail_mail" ||
$driver === 'mail');
299 // get emails from headers, since these are
300 // combination of name and email addresses.
301 if (!empty($headers['Cc'])) {
302 $to[] = $headers['Cc'] ??
NULL;
304 if (!empty($headers['Bcc'])) {
305 $to[] = $headers['Bcc'] ??
NULL;
306 unset($headers['Bcc']);
310 if (is_object($mailer)) {
312 $result = $mailer->send($to, $headers, $message);
314 catch (Exception
$e) {
315 \Civi
::log()->error('Mailing error: ' . $e->getMessage());
316 CRM_Core_Session
::setStatus(ts('Unable to send email. Please report this message to the site administrator'), ts('Mailing Error'), 'error');
319 if (is_a($result, 'PEAR_Error')) {
320 $message = self
::errorMessage($mailer, $result);
321 // append error message in case multiple calls are being made to
322 // this method in the course of sending a batch of messages.
323 \Civi
::log()->error('Mailing error: ' . $message);
324 CRM_Core_Session
::setStatus(ts('Unable to send email. Please report this message to the site administrator'), ts('Mailing Error'), 'error');
328 CRM_Utils_Hook
::postEmailSend($params);
340 public static function errorMessage($mailer, $result) {
341 $message = '<p>' . ts('An error occurred when CiviCRM attempted to send an email (via %1). If you received this error after submitting on online contribution or event registration - the transaction was completed, but we were unable to send the email receipt.', [
343 ]) . '</p>' . '<p>' . ts('The mail library returned the following error message:') . '<br /><span class="font-red"><strong>' . $result->getMessage() . '</strong></span></p>' . '<p>' . ts('This is probably related to a problem in your Outbound Email Settings (Administer CiviCRM » System Settings » Outbound Email), OR the FROM email address specifically configured for your contribution page or event. Possible causes are:') . '</p>';
345 if (is_a($mailer, 'Mail_smtp')) {
346 $message .= '<ul>' . '<li>' . ts('Your SMTP Username or Password are incorrect.') . '</li>' . '<li>' . ts('Your SMTP Server (machine) name is incorrect.') . '</li>' . '<li>' . ts('You need to use a Port other than the default port 25 in your environment.') . '</li>' . '<li>' . ts('Your SMTP server is just not responding right now (it is down for some reason).') . '</li>';
349 $message .= '<ul>' . '<li>' . ts('Your Sendmail path is incorrect.') . '</li>' . '<li>' . ts('Your Sendmail argument is incorrect.') . '</li>';
352 $message .= '<li>' . ts('The FROM Email Address configured for this feature may not be a valid sender based on your email service provider rules.') . '</li>' . '</ul>' . '<p>' . ts('Check <a href="%1">this page</a> for more information.', [
353 1 => CRM_Utils_System
::docURL2('user/advanced-configuration/email-system-configuration', TRUE),
365 public static function logger(&$to, &$headers, &$message) {
366 CRM_Utils_Mail_Logger
::log($to, $headers, $message);
370 * Get the email address itself from a formatted full name + address string
374 * @param string $header
375 * The full name + email address string.
378 * the plucked email address
380 public static function pluckEmailFromHeader($header) {
381 preg_match('/<([^<]*)>$/', $header, $matches);
383 if (isset($matches[1])) {
390 * Get the Active outBound email.
393 * TRUE if valid outBound email configuration found, false otherwise.
395 public static function validOutBoundMail() {
396 $mailingInfo = Civi
::settings()->get('mailing_backend');
397 if ($mailingInfo['outBound_option'] == CRM_Mailing_Config
::OUTBOUND_OPTION_MAIL
) {
400 elseif ($mailingInfo['outBound_option'] == CRM_Mailing_Config
::OUTBOUND_OPTION_SMTP
) {
401 if (!isset($mailingInfo['smtpServer']) ||
$mailingInfo['smtpServer'] == '' ||
402 $mailingInfo['smtpServer'] == 'YOUR SMTP SERVER' ||
403 ($mailingInfo['smtpAuth'] && ($mailingInfo['smtpUsername'] == '' ||
$mailingInfo['smtpPassword'] == ''))
409 elseif ($mailingInfo['outBound_option'] == CRM_Mailing_Config
::OUTBOUND_OPTION_SENDMAIL
) {
410 if (!$mailingInfo['sendmail_path'] ||
!$mailingInfo['sendmail_args']) {
415 elseif ($mailingInfo['outBound_option'] == CRM_Mailing_Config
::OUTBOUND_OPTION_REDIRECT_TO_DB
) {
423 * @param array $params
427 public static function setMimeParams($message, $params = NULL) {
428 static $mimeParams = NULL;
432 'text_encoding' => '8bit',
433 'html_encoding' => '8bit',
434 'head_charset' => 'utf-8',
435 'text_charset' => 'utf-8',
436 'html_charset' => 'utf-8',
439 $params = $mimeParams;
441 return $message->get($params);
445 * @param string $name
446 * @param string $email
447 * @param bool $useQuote
449 * @return null|string
451 public static function formatRFC822Email($name, $email, $useQuote = FALSE) {
456 // strip out double quotes if present at the beginning AND end
457 if (substr($name, 0, 1) == '"' &&
458 substr($name, -1, 1) == '"'
460 $name = substr($name, 1, -1);
464 // escape the special characters
465 $name = str_replace(['<', '"', '>'],
469 if (strpos($name, ',') !== FALSE ||
472 // quote the string if it has a comma
473 $name = '"' . $name . '"';
479 $result .= "<{$email}>";
484 * Takes a string and checks to see if it needs to be escaped / double quoted
485 * and if so does the needful and return the formatted name
487 * This code has been copied and adapted from ezc/Mail/src/tools.php
489 * @param string $name
493 public static function formatRFC2822Name($name) {
496 // remove the quotes around the name part if they are already there
497 if (substr($name, 0, 1) == '"' && substr($name, -1) == '"') {
498 $name = substr($name, 1, -1);
501 // add slashes to " and \ and surround the name part with quotes
502 if (strpbrk($name, ",@<>:;'\"") !== FALSE) {
503 $name = '"' . addcslashes($name, '\\"') . '"';
511 * @param string $fileName
512 * @param string $html
513 * @param string $format
517 public static function appendPDF($fileName, $html, $format = NULL) {
518 $pdf_filename = CRM_Core_Config
::singleton()->templateCompileDir
. CRM_Utils_File
::makeFileName($fileName);
521 // xmlns attribute is required in XHTML but it is invalid in HTML,
522 // Also the namespace "xmlns=http://www.w3.org/1999/xhtml" is default,
523 // and will be added to the <html> tag even if you do not include it.
524 $html = preg_replace('/(<html)(.+?xmlns=["\'].[^\s]+["\'])(.+)?(>)/', '\1\3\4', $html);
526 file_put_contents($pdf_filename, CRM_Utils_PDF_Utils
::html2pdf($html,
532 'fullPath' => $pdf_filename,
533 'mime_type' => 'application/pdf',
534 'cleanName' => $fileName,
539 * Format an email string from email fields.
541 * @param array $fields
544 * The formatted email string.
546 public static function format($fields) {
547 $formattedEmail = '';
548 if (!empty($fields['email'])) {
549 $formattedEmail = $fields['email'];
552 $formattedSuffix = [];
553 if (!empty($fields['is_bulkmail'])) {
554 $formattedSuffix[] = '(' . ts('Bulk') . ')';
556 if (!empty($fields['on_hold'])) {
557 if ($fields['on_hold'] == 2) {
558 $formattedSuffix[] = '(' . ts('On Hold - Opt Out') . ')';
561 $formattedSuffix[] = '(' . ts('On Hold') . ')';
564 if (!empty($fields['signature_html']) ||
!empty($fields['signature_text'])) {
565 $formattedSuffix[] = '(' . ts('Signature') . ')';
568 // Add suffixes on a new line, if there is any.
569 if (!empty($formattedSuffix)) {
570 $formattedEmail .= "\n" . implode(' ', $formattedSuffix);
573 return $formattedEmail;
577 * When passed a value, returns the value if it's non-numeric.
578 * If it's numeric, look up the display name and email of the corresponding
579 * contact ID in RFC822 format.
581 * @param string $from
582 * civicrm_email.id or formatted "From address", eg. 12 or "Fred Bloggs" <fred@example.org>
584 * The RFC822-formatted email header (display name + address)
586 public static function formatFromAddress($from) {
587 if (is_numeric($from)) {
588 $result = civicrm_api3('Email', 'get', [
590 'return' => ['contact_id.display_name', 'email'],
593 $from = '"' . $result['contact_id.display_name'] . '" <' . $result['email'] . '>';