api/v3/Mailing.php

   1 <?php
   2
   3 /*
   4  +--------------------------------------------------------------------+
   5  | CiviCRM version 4.5                                                |
   6  +--------------------------------------------------------------------+
   7  | Copyright CiviCRM LLC (c) 2004-2014                                |
   8  +--------------------------------------------------------------------+
   9  | This file is a part of CiviCRM.                                    |
  10  |                                                                    |
  11  | CiviCRM is free software; you can copy, modify, and distribute it  |
  12  | under the terms of the GNU Affero General Public License           |
  13  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  14  |                                                                    |
  15  | CiviCRM is distributed in the hope that it will be useful, but     |
  16  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  17  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  18  | See the GNU Affero General Public License for more details.        |
  19  |                                                                    |
  20  | You should have received a copy of the GNU Affero General Public   |
  21  | License and the CiviCRM Licensing Exception along                  |
  22  | with this program; if not, contact CiviCRM LLC                     |
  23  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  24  | GNU Affero General Public License or the licensing of CiviCRM,     |
  25  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  26  +--------------------------------------------------------------------+
  27 */
  28
  29 /**
  30  *
  31  * APIv3 functions for registering/processing mailing events.
  32  *
  33  * @package CiviCRM_APIv3
  34  * @subpackage API_Mailing
  35  * @copyright CiviCRM LLC (c) 2004-2014
  36  * $Id$
  37  *
  38  */
  39
  40 /**
  41  * Files required for this package
  42  */
  43
  44 /**
  45  * Handle a create event.
  46  *
  47  * @param array $params
  48  * @param array $ids
  49  *
  50  * @return array API Success Array
  51  */
  52 function civicrm_api3_mailing_create($params, $ids = array()) {
  53   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  54 }
  55
  56 function civicrm_api3_mailing_get_token($params) {
  57   if (!array_key_exists("usage", $params)) {
  58     throw new API_Exception('Mandatory keys missing from params array: entity');
  59   }
  60
  61   $tokens = CRM_Core_SelectValues::contactTokens();
  62   switch ($params['usage']) {
  63     case 'Mailing' :
  64       $tokens = array_merge(CRM_Core_SelectValues::mailingTokens(), $tokens);
  65       break;
  66     case 'ScheduleEventReminder' :
  67       $tokens = array_merge(CRM_Core_SelectValues::activityTokens(), $tokens);
  68       $tokens = array_merge(CRM_Core_SelectValues::eventTokens(), $tokens);
  69       $tokens = array_merge(CRM_Core_SelectValues::membershipTokens(), $tokens);
  70       break;
  71     case 'ManageEventScheduleReminder' :
  72       $tokens = array_merge(CRM_Core_SelectValues::eventTokens(), $tokens);
  73       break;
  74   }
  75
  76   return CRM_Utils_Token::formatTokensForDisplay($tokens);
  77 }
  78
  79 /**
  80  * Adjust Metadata for Create action
  81  *
  82  * The metadata is used for setting defaults, documentation & validation
  83  * @param array $params array or parameters determined by getfields
  84  */
  85 function _civicrm_api3_mailing_create_spec(&$params) {
  86   $params['name']['api.required'] = 1;
  87   $params['subject']['api.required'] = 1;
  88   $params['created_id']['api.required'] = 1;
  89   $params['created_id']['api.default'] = 'user_contact_id';
  90   $params['api.mailing_job.create']['api.default'] = 1;
  91   $params['api.mailing_job.create']['title'] = 'Schedule Mailing?';
  92 }
  93
  94 /**
  95  * Handle a delete event.
  96  *
  97  * @param array $params
  98  * @param array $ids
  99  *
 100  * @return array API Success Array
 101  */
 102 function civicrm_api3_mailing_delete($params, $ids = array()) {
 103   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
 104 }
 105
 106
 107 /**
 108  * Handle a get event.
 109  *
 110  * @param array $params
 111  * @return array
 112  */
 113 function civicrm_api3_mailing_get($params) {
 114   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
 115 }
 116
 117 /**
 118  * Process a bounce event by passing through to the BAOs.
 119  *
 120  * @param array $params
 121  *
 122  * @throws API_Exception
 123  * @return array
 124  */
 125 function civicrm_api3_mailing_event_bounce($params) {
 126   $body = $params['body'];
 127   unset($params['body']);
 128
 129   $params += CRM_Mailing_BAO_BouncePattern::match($body);
 130
 131   if (CRM_Mailing_Event_BAO_Bounce::create($params)) {
 132     return civicrm_api3_create_success($params);
 133   }
 134   else {
 135     throw new API_Exception(ts('Queue event could not be found'),'no_queue_event
 136       ');
 137   }
 138 }
 139
 140 /**
 141  * Adjust Metadata for bounce_spec action
 142  *
 143  * The metadata is used for setting defaults, documentation & validation
 144  * @param array $params array or parameters determined by getfields
 145  */
 146 function _civicrm_api3_mailing_event_bounce_spec(&$params) {
 147   $params['job_id']['api.required'] = 1;
 148   $params['job_id']['title'] = 'Job ID';
 149   $params['event_queue_id']['api.required'] = 1;
 150   $params['event_queue_id']['title'] = 'Event Queue ID';
 151   $params['hash']['api.required'] = 1;
 152   $params['hash']['title'] = 'Hash';
 153   $params['body']['api.required'] = 1;
 154   $params['body']['title'] = 'Body';
 155 }
 156
 157 /**
 158  * Handle a confirm event
 159  * @deprecated
 160  *
 161  * @param array $params
 162  *
 163  * @return array
 164  */
 165 function civicrm_api3_mailing_event_confirm($params) {
 166   return civicrm_api('mailing_event_confirm', 'create', $params);
 167 }
 168
 169 /**
 170  * @deprecated api notice
 171  * @return array of deprecated actions
 172  */
 173 function _civicrm_api3_mailing_deprecation() {
 174   return array('event_confirm' => 'Mailing api "event_confirm" action is deprecated. Use the mailing_event_confirm api instead.');
 175 }
 176
 177 /**
 178  * Handle a reply event
 179  *
 180  * @param array $params
 181  *
 182  * @return array
 183  */
 184 function civicrm_api3_mailing_event_reply($params) {
 185   $job       = $params['job_id'];
 186   $queue     = $params['event_queue_id'];
 187   $hash      = $params['hash'];
 188   $replyto   = $params['replyTo'];
 189   $bodyTxt   = CRM_Utils_Array::value('bodyTxt', $params);
 190   $bodyHTML  = CRM_Utils_Array::value('bodyHTML', $params);
 191   $fullEmail = CRM_Utils_Array::value('fullEmail', $params);
 192
 193   $mailing = CRM_Mailing_Event_BAO_Reply::reply($job, $queue, $hash, $replyto);
 194
 195   if (empty($mailing)) {
 196     return civicrm_api3_create_error('Queue event could not be found');
 197   }
 198
 199   CRM_Mailing_Event_BAO_Reply::send($queue, $mailing, $bodyTxt, $replyto, $bodyHTML, $fullEmail);
 200
 201   return civicrm_api3_create_success($params);
 202 }
 203
 204 /**
 205  * Adjust Metadata for event_reply action
 206  *
 207  * The metadata is used for setting defaults, documentation & validation
 208  * @param array $params array or parameters determined by getfields
 209  */
 210 function _civicrm_api3_mailing_event_reply_spec(&$params) {
 211   $params['job_id']['api.required'] = 1;
 212   $params['job_id']['title'] = 'Job ID';
 213   $params['event_queue_id']['api.required'] = 1;
 214   $params['event_queue_id']['title'] = 'Event Queue ID';
 215   $params['hash']['api.required'] = 1;
 216   $params['hash']['title'] = 'Hash';
 217   $params['replyTo']['api.required'] = 0;
 218   $params['replyTo']['title'] = 'Reply To';//doesn't really explain adequately
 219 }
 220
 221 /**
 222  * Handle a forward event
 223  *
 224  * @param array $params
 225  *
 226  * @return array
 227  */
 228 function civicrm_api3_mailing_event_forward($params) {
 229   $job       = $params['job_id'];
 230   $queue     = $params['event_queue_id'];
 231   $hash      = $params['hash'];
 232   $email     = $params['email'];
 233   $fromEmail = CRM_Utils_Array::value('fromEmail', $params);
 234   $params    = CRM_Utils_Array::value('params', $params);
 235
 236   $forward = CRM_Mailing_Event_BAO_Forward::forward($job, $queue, $hash, $email, $fromEmail, $params);
 237
 238   if ($forward) {
 239     return civicrm_api3_create_success($params);
 240   }
 241
 242   return civicrm_api3_create_error('Queue event could not be found');
 243 }
 244
 245 /**
 246  * Adjust Metadata for event_forward action
 247  *
 248  * The metadata is used for setting defaults, documentation & validation
 249  * @param array $params array or parameters determined by getfields
 250  */
 251 function _civicrm_api3_mailing_event_forward_spec(&$params) {
 252   $params['job_id']['api.required'] = 1;
 253   $params['job_id']['title'] = 'Job ID';
 254   $params['event_queue_id']['api.required'] = 1;
 255   $params['event_queue_id']['title'] = 'Event Queue ID';
 256   $params['hash']['api.required'] = 1;
 257   $params['hash']['title'] = 'Hash';
 258   $params['email']['api.required'] = 1;
 259   $params['email']['title'] = 'Forwarded to Email';
 260 }
 261
 262 /**
 263  * Handle a click event
 264  *
 265  * @param array $params
 266  *
 267  * @return array
 268  */
 269 function civicrm_api3_mailing_event_click($params) {
 270   civicrm_api3_verify_mandatory($params,
 271     'CRM_Mailing_Event_DAO_TrackableURLOpen',
 272     array('event_queue_id', 'url_id'),
 273     FALSE
 274   );
 275
 276   $url_id = $params['url_id'];
 277   $queue = $params['event_queue_id'];
 278
 279   $url = CRM_Mailing_Event_BAO_TrackableURLOpen::track($queue, $url_id);
 280
 281   $values             = array();
 282   $values['url']      = $url;
 283   $values['is_error'] = 0;
 284
 285   return civicrm_api3_create_success($values);
 286 }
 287
 288 /**
 289  * Handle an open event
 290  *
 291  * @param array $params
 292  *
 293  * @return array
 294  */
 295 function civicrm_api3_mailing_event_open($params) {
 296
 297   civicrm_api3_verify_mandatory($params,
 298     'CRM_Mailing_Event_DAO_Opened',
 299     array('event_queue_id'),
 300     FALSE
 301   );
 302
 303   $queue = $params['event_queue_id'];
 304   $success = CRM_Mailing_Event_BAO_Opened::open($queue);
 305
 306   if (!$success) {
 307     return civicrm_api3_create_error('mailing open event failed');
 308   }
 309
 310   return civicrm_api3_create_success($params);
 311 }
 312
 313 function civicrm_api3_mailing_preview($params) {
 314   civicrm_api3_verify_mandatory($params,
 315     'CRM_Mailing_DAO_Mailing',
 316     array('id'),
 317     FALSE
 318   );
 319
 320   $fromEmail = NULL;
 321   if (!empty($params['from_email'])) {
 322     $fromEmail = $params['from_email'];
 323   }
 324
 325   $session = CRM_Core_Session::singleton();
 326   $mailing = new CRM_Mailing_BAO_Mailing();
 327   $mailing->id = $params['id'];
 328   $mailing->find(TRUE);
 329
 330   CRM_Mailing_BAO_Mailing::tokenReplace($mailing);
 331
 332   // get and format attachments
 333   $attachments = CRM_Core_BAO_File::getEntityFile('civicrm_mailing', $mailing->id);
 334
 335   $returnProperties = $mailing->getReturnProperties();
 336   $contactID = CRM_Utils_Array::value('contact_id', $params);
 337   if (!$contactID) {
 338     $contactID = $session->get('userID');
 339   }
 340   $mailingParams = array('contact_id' => $contactID);
 341
 342   $details = CRM_Utils_Token::getTokenDetails($mailingParams, $returnProperties, TRUE, TRUE, NULL, $mailing->getFlattenedTokens());
 343
 344   $mime = &$mailing->compose(NULL, NULL, NULL, $session->get('userID'), $fromEmail, $fromEmail,
 345     TRUE, $details[0][$contactID], $attachments
 346   );
 347
 348   return civicrm_api3_create_success(array(
 349     'id' => $params['id'],
 350     'contact_id' => $contactID,
 351     'subject' => $mime->_headers['Subject'],
 352     'body_html' => $mime->getHTMLBody(),
 353     'body_text' => $mime->getTXTBody(),
 354   ));
 355 }
 356
 357 function civicrm_api3_mailing_send_test($params) {
 358   if (!array_key_exists('test_group', $params) && !array_key_exists('test_email', $params)) {
 359     throw new API_Exception("Mandatory key(s) missing from params array: test_group and/or test_email field are required" );
 360   }
 361   civicrm_api3_verify_mandatory($params,
 362     'CRM_Mailing_DAO_MailingJob',
 363     array('mailing_id'),
 364     FALSE
 365   );
 366
 367   $testEmailParams = _civicrm_api3_generic_replace_base_params($params);
 368   $testEmailParams['is_test'] = 1;
 369   $job = civicrm_api3('MailingJob', 'create', $testEmailParams);
 370   $testEmailParams['job_id'] = $job['id'];
 371   $testEmailParams['emails'] = explode(',', $testEmailParams['test_email']);
 372   if (!empty($params['test_email'])) {
 373     $query = "
 374 SELECT     e.id, e.contact_id, e.email
 375 FROM       civicrm_email e
 376 INNER JOIN civicrm_contact c ON e.contact_id = c.id
 377 WHERE      e.email IN ('" . implode("','", $testEmailParams['emails']) . "')
 378 AND        e.on_hold = 0
 379 AND        c.is_opt_out = 0
 380 AND        c.do_not_email = 0
 381 AND        c.is_deceased = 0
 382 GROUP BY   e.id
 383 ORDER BY   e.is_bulkmail DESC, e.is_primary DESC
 384 ";
 385     $dao = CRM_Core_DAO::executeQuery($query);
 386     $emailDetail = array();
 387     // fetch contact_id and email id for all existing emails
 388     while ($dao->fetch()) {
 389       $emailDetail[$dao->email] = array(
 390         'contact_id' => $dao->contact_id,
 391         'email_id' => $dao->id,
 392       );
 393     }
 394     $dao->free();
 395     foreach ($testEmailParams['emails'] as $key => $email) {
 396       $email = trim($email);
 397       $contactId = $emailId = NULL;
 398       if (array_key_exists($email, $emailDetail)) {
 399         $emailId = $emailDetail[$email]['email_id'];
 400         $contactId = $emailDetail[$email]['contact_id'];
 401       }
 402       if (!$contactId) {
 403         //create new contact.
 404         $contact   = civicrm_api3('Contact', 'create',
 405           array('contact_type' => 'Individual',
 406             'email' => $email,
 407             'api.Email.get' => array('return' => 'id')
 408           )
 409         );
 410         $contactId = $contact['id'];
 411         $emailId   = $contact['values'][$contactId]['api.Email.get']['id'];
 412       }
 413       civicrm_api3('MailingEventQueue', 'create',
 414         array('job_id' => $job['id'],
 415           'email_id' => $emailId,
 416           'contact_id' => $contactId
 417         )
 418       );
 419     }
 420   }
 421
 422   $isComplete = FALSE;
 423   $config = CRM_Core_Config::singleton();
 424   $mailerJobSize = (property_exists($config, 'mailerJobSize')) ? $config->mailerJobSize : NULL;
 425   while (!$isComplete) {
 426     // Q: In CRM_Mailing_BAO_Mailing::processQueue(), the three runJobs*()
 427     // functions are all called. Why does Mailing.send_test only call one?
 428     // CRM_Mailing_BAO_MailingJob::runJobs_pre($mailerJobSize, NULL);
 429     $isComplete = CRM_Mailing_BAO_MailingJob::runJobs($testEmailParams);
 430     // CRM_Mailing_BAO_MailingJob::runJobs_post(NULL);
 431   }
 432
 433   //return delivered mail info
 434   $mailDelivered = CRM_Mailing_Event_BAO_Delivered::getRows($params['mailing_id'], $job['id'], TRUE, NULL, NULL, NULL, TRUE);
 435
 436   return civicrm_api3_create_success($mailDelivered);
 437 }
 438
 439 /**
 440  * Adjust Metadata for send_mail action
 441  *
 442  * The metadata is used for setting defaults, documentation & validation
 443  * @param array $params array or parameters determined by getfields
 444  */
 445 function _civicrm_api3_mailing_stats_spec(&$params) {
 446   $params['date']['api.default'] = 'now';
 447   $params['date']['title'] = 'Date';
 448 }
 449
 450 function civicrm_api3_mailing_stats($params) {
 451   civicrm_api3_verify_mandatory($params,
 452     'CRM_Mailing_DAO_MailingJob',
 453     array('mailing_id'),
 454     FALSE
 455   );
 456
 457   if ($params['date'] == 'now') {
 458     $params['date'] = date('YmdHis');
 459   }
 460   else {
 461     $params['date'] = CRM_Utils_Date::processDate($params['date'] . ' ' . $params['date_time']);
 462   }
 463
 464   $stats[$params['mailing_id']] = array();
 465   if (empty($params['job_id'])) {
 466     $params['job_id'] = NULL;
 467   }
 468   foreach (array('Delivered', 'Bounces', 'Unsubscribers', 'Unique Clicks', 'Opened') as $detail) {
 469     switch ($detail) {
 470       case 'Delivered':
 471         $stats[$params['mailing_id']] += array(
 472           $detail =>  CRM_Mailing_Event_BAO_Delivered::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date'])
 473         );
 474         break;
 475       case 'Bounces':
 476         $stats[$params['mailing_id']] += array(
 477           $detail =>  CRM_Mailing_Event_BAO_Bounce::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date'])
 478         );
 479         break;
 480       case 'Unsubscribers':
 481         $stats[$params['mailing_id']] += array(
 482           $detail =>  CRM_Mailing_Event_BAO_Unsubscribe::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, NULL, $params['date'])
 483         );
 484         break;
 485       case 'Unique Clicks':
 486         $stats[$params['mailing_id']] += array(
 487           $detail =>  CRM_Mailing_Event_BAO_TrackableURLOpen::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, NULL, $params['date'])
 488         );
 489         break;
 490       case 'Opened':
 491         $stats[$params['mailing_id']] += array(
 492           $detail =>  CRM_Mailing_Event_BAO_Opened::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date'])
 493         );
 494         break;
 495     }
 496   }
 497   return civicrm_api3_create_success($stats);
 498 }
 499
 500 /**
 501  * Fix the reset dates on the email record based on when a mail was last delivered
 502  * We only consider mailings that were completed and finished in the last 3 to 7 days
 503  * Both the min and max days can be set via the params
 504  */
 505 function civicrm_api3_mailing_update_email_resetdate($params) {
 506   CRM_Mailing_Event_BAO_Delivered::updateEmailResetDate(
 507     CRM_Utils_Array::value('minDays', $params, 3),
 508     CRM_Utils_Array::value('maxDays', $params, 3)
 509   );
 510   return civicrm_api3_create_success();
 511 }