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