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 /**
 314  * Generate a list of likely recipients for a (hypothetical) mailing.
 315  *
 316  * "Mailing.preview_recipients" == "Mailing.create" + "MailingRecipients.get" + "rollback"
 317  *
 318  * Ideally, we could add a "force_rollback" option to the API; then downstream code could
 319  * combine the actions without needing this function.
 320  *
 321  * @param array $params
 322  * @return array list of recipients
 323  * @throws API_Exception
 324  */
 325 function civicrm_api3_mailing_preview_recipients($params) {
 326   static $nextId = 0;
 327   $savePoint = "civimail_preview_" . ++$nextId;
 328   $tx = new CRM_Core_Transaction();
 329   CRM_Core_DAO::executeQuery("SAVEPOINT $savePoint");
 330
 331   // We manually apply defaults (rather than using API defaults) because
 332   // (a) these are temporary/non-sense values and (b) we want to
 333   // apply defaults regardless of whether mailing has NULL/''/real-value.
 334   $params['name'] = 'Placeholder (not saved)';
 335   $params['subject'] = 'Placeholder (not saved)';
 336   $params['scheduled_date'] = date('YmdHis', time() + 24*60*60);
 337
 338   // "Mailing.preview_recipients" == "Mailing.create"+"MailingRecipients.get"
 339   $params['debug'] = 1;
 340   $params['version'] = 3;
 341   $params['options']['force_rollback'] = 1;
 342   $params['api.MailingRecipients.get'] = array(
 343     'options' => array(
 344       'limit' => isset($params['options']['limit']) ? $params['options']['limit'] : 1000,
 345     ),
 346     'api.contact.getvalue' => array(
 347       'return' => 'display_name',
 348     ),
 349     'api.email.getvalue' => array(
 350       'return' => 'email',
 351     ),
 352   );
 353
 354   try {
 355     $mailing = civicrm_api3('Mailing', 'create', $params);
 356   } catch (Exception $ex) {
 357     CRM_Core_DAO::executeQuery("ROLLBACK TO SAVEPOINT $savePoint");
 358     throw $ex;
 359   }
 360
 361   CRM_Core_DAO::executeQuery("ROLLBACK TO SAVEPOINT $savePoint");
 362   return civicrm_api3_create_success($mailing['values'][$mailing['id']]['api.MailingRecipients.get']['values']);
 363 }
 364
 365 function civicrm_api3_mailing_preview($params) {
 366   civicrm_api3_verify_mandatory($params,
 367     'CRM_Mailing_DAO_Mailing',
 368     array('id'),
 369     FALSE
 370   );
 371
 372   $fromEmail = NULL;
 373   if (!empty($params['from_email'])) {
 374     $fromEmail = $params['from_email'];
 375   }
 376
 377   $session = CRM_Core_Session::singleton();
 378   $mailing = new CRM_Mailing_BAO_Mailing();
 379   $mailing->id = $params['id'];
 380   $mailing->find(TRUE);
 381
 382   CRM_Mailing_BAO_Mailing::tokenReplace($mailing);
 383
 384   // get and format attachments
 385   $attachments = CRM_Core_BAO_File::getEntityFile('civicrm_mailing', $mailing->id);
 386
 387   $returnProperties = $mailing->getReturnProperties();
 388   $contactID = CRM_Utils_Array::value('contact_id', $params);
 389   if (!$contactID) {
 390     $contactID = $session->get('userID');
 391   }
 392   $mailingParams = array('contact_id' => $contactID);
 393
 394   $details = CRM_Utils_Token::getTokenDetails($mailingParams, $returnProperties, TRUE, TRUE, NULL, $mailing->getFlattenedTokens());
 395
 396   $mime = &$mailing->compose(NULL, NULL, NULL, $session->get('userID'), $fromEmail, $fromEmail,
 397     TRUE, $details[0][$contactID], $attachments
 398   );
 399
 400   return civicrm_api3_create_success(array(
 401     'id' => $params['id'],
 402     'contact_id' => $contactID,
 403     'subject' => $mime->_headers['Subject'],
 404     'html' => $mime->getHTMLBody(),
 405     'text' => $mime->getTXTBody(),
 406   ));
 407 }
 408
 409 function civicrm_api3_mailing_send_test($params) {
 410   if (!array_key_exists('test_group', $params) && !array_key_exists('test_email', $params)) {
 411     throw new API_Exception("Mandatory key(s) missing from params array: test_group and/or test_email field are required" );
 412   }
 413   civicrm_api3_verify_mandatory($params,
 414     'CRM_Mailing_DAO_MailingJob',
 415     array('mailing_id'),
 416     FALSE
 417   );
 418
 419   $testEmailParams = _civicrm_api3_generic_replace_base_params($params);
 420   $testEmailParams['is_test'] = 1;
 421   $job = civicrm_api3('MailingJob', 'create', $testEmailParams);
 422   $testEmailParams['job_id'] = $job['id'];
 423   $testEmailParams['emails'] = explode(',', $testEmailParams['test_email']);
 424   if (!empty($params['test_email'])) {
 425     $query = "
 426 SELECT     e.id, e.contact_id, e.email
 427 FROM       civicrm_email e
 428 INNER JOIN civicrm_contact c ON e.contact_id = c.id
 429 WHERE      e.email IN ('" . implode("','", $testEmailParams['emails']) . "')
 430 AND        e.on_hold = 0
 431 AND        c.is_opt_out = 0
 432 AND        c.do_not_email = 0
 433 AND        c.is_deceased = 0
 434 GROUP BY   e.id
 435 ORDER BY   e.is_bulkmail DESC, e.is_primary DESC
 436 ";
 437     $dao = CRM_Core_DAO::executeQuery($query);
 438     $emailDetail = array();
 439     // fetch contact_id and email id for all existing emails
 440     while ($dao->fetch()) {
 441       $emailDetail[$dao->email] = array(
 442         'contact_id' => $dao->contact_id,
 443         'email_id' => $dao->id,
 444       );
 445     }
 446     $dao->free();
 447     foreach ($testEmailParams['emails'] as $key => $email) {
 448       $email = trim($email);
 449       $contactId = $emailId = NULL;
 450       if (array_key_exists($email, $emailDetail)) {
 451         $emailId = $emailDetail[$email]['email_id'];
 452         $contactId = $emailDetail[$email]['contact_id'];
 453       }
 454       if (!$contactId) {
 455         //create new contact.
 456         $contact   = civicrm_api3('Contact', 'create',
 457           array('contact_type' => 'Individual',
 458             'email' => $email,
 459             'api.Email.get' => array('return' => 'id')
 460           )
 461         );
 462         $contactId = $contact['id'];
 463         $emailId   = $contact['values'][$contactId]['api.Email.get']['id'];
 464       }
 465       civicrm_api3('MailingEventQueue', 'create',
 466         array('job_id' => $job['id'],
 467           'email_id' => $emailId,
 468           'contact_id' => $contactId
 469         )
 470       );
 471     }
 472   }
 473
 474   $isComplete = FALSE;
 475   $config = CRM_Core_Config::singleton();
 476   $mailerJobSize = (property_exists($config, 'mailerJobSize')) ? $config->mailerJobSize : NULL;
 477   while (!$isComplete) {
 478     // Q: In CRM_Mailing_BAO_Mailing::processQueue(), the three runJobs*()
 479     // functions are all called. Why does Mailing.send_test only call one?
 480     // CRM_Mailing_BAO_MailingJob::runJobs_pre($mailerJobSize, NULL);
 481     $isComplete = CRM_Mailing_BAO_MailingJob::runJobs($testEmailParams);
 482     // CRM_Mailing_BAO_MailingJob::runJobs_post(NULL);
 483   }
 484
 485   //return delivered mail info
 486   $mailDelivered = CRM_Mailing_Event_BAO_Delivered::getRows($params['mailing_id'], $job['id'], TRUE, NULL, NULL, NULL, TRUE);
 487
 488   return civicrm_api3_create_success($mailDelivered);
 489 }
 490
 491 /**
 492  * Adjust Metadata for send_mail action
 493  *
 494  * The metadata is used for setting defaults, documentation & validation
 495  * @param array $params array or parameters determined by getfields
 496  */
 497 function _civicrm_api3_mailing_stats_spec(&$params) {
 498   $params['date']['api.default'] = 'now';
 499   $params['date']['title'] = 'Date';
 500 }
 501
 502 function civicrm_api3_mailing_stats($params) {
 503   civicrm_api3_verify_mandatory($params,
 504     'CRM_Mailing_DAO_MailingJob',
 505     array('mailing_id'),
 506     FALSE
 507   );
 508
 509   if ($params['date'] == 'now') {
 510     $params['date'] = date('YmdHis');
 511   }
 512   else {
 513     $params['date'] = CRM_Utils_Date::processDate($params['date'] . ' ' . $params['date_time']);
 514   }
 515
 516   $stats[$params['mailing_id']] = array();
 517   if (empty($params['job_id'])) {
 518     $params['job_id'] = NULL;
 519   }
 520   foreach (array('Delivered', 'Bounces', 'Unsubscribers', 'Unique Clicks', 'Opened') as $detail) {
 521     switch ($detail) {
 522       case 'Delivered':
 523         $stats[$params['mailing_id']] += array(
 524           $detail =>  CRM_Mailing_Event_BAO_Delivered::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date'])
 525         );
 526         break;
 527       case 'Bounces':
 528         $stats[$params['mailing_id']] += array(
 529           $detail =>  CRM_Mailing_Event_BAO_Bounce::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date'])
 530         );
 531         break;
 532       case 'Unsubscribers':
 533         $stats[$params['mailing_id']] += array(
 534           $detail =>  CRM_Mailing_Event_BAO_Unsubscribe::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, NULL, $params['date'])
 535         );
 536         break;
 537       case 'Unique Clicks':
 538         $stats[$params['mailing_id']] += array(
 539           $detail =>  CRM_Mailing_Event_BAO_TrackableURLOpen::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, NULL, $params['date'])
 540         );
 541         break;
 542       case 'Opened':
 543         $stats[$params['mailing_id']] += array(
 544           $detail =>  CRM_Mailing_Event_BAO_Opened::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date'])
 545         );
 546         break;
 547     }
 548   }
 549   return civicrm_api3_create_success($stats);
 550 }
 551
 552 /**
 553  * Fix the reset dates on the email record based on when a mail was last delivered
 554  * We only consider mailings that were completed and finished in the last 3 to 7 days
 555  * Both the min and max days can be set via the params
 556  */
 557 function civicrm_api3_mailing_update_email_resetdate($params) {
 558   CRM_Mailing_Event_BAO_Delivered::updateEmailResetDate(
 559     CRM_Utils_Array::value('minDays', $params, 3),
 560     CRM_Utils_Array::value('maxDays', $params, 3)
 561   );
 562   return civicrm_api3_create_success();
 563 }