api/v3/Mailing.php

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