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
  81
  82 /**
  83  * Adjust Metadata for Create action
  84  *
  85  * The metadata is used for setting defaults, documentation & validation
  86  * @param array $params array or parameters determined by getfields
  87  */
  88 function _civicrm_api3_mailing_create_spec(&$params) {
  89   $params['name']['api.required'] = 1;
  90   $params['subject']['api.required'] = 1;
  91   // should be able to default to 'user_contact_id' & have it work but it didn't work in test so
  92   // making required for simplicity
  93   $params['created_id']['api.required'] = 1;
  94   $params['api.mailing_job.create']['api.default'] = 1;
  95   $params['api.mailing_job.create']['title'] = 'Schedule Mailing?';
  96 }
  97
  98 /**
  99  * Handle a delete event.
 100  *
 101  * @param array $params
 102  * @param array $ids
 103  *
 104  * @return array API Success Array
 105  */
 106 function civicrm_api3_mailing_delete($params, $ids = array()) {
 107         return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
 108 }
 109
 110
 111 /**
 112  * Handle a get event.
 113  *
 114  * @param array $params
 115  * @return array
 116  */
 117 function civicrm_api3_mailing_get($params) {
 118         return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
 119 }
 120
 121 /**
 122  * Process a bounce event by passing through to the BAOs.
 123  *
 124  * @param array $params
 125  *
 126  * @throws API_Exception
 127  * @return array
 128  */
 129 function civicrm_api3_mailing_event_bounce($params) {
 130
 131         $body = $params['body'];
 132         unset($params['body']);
 133
 134         $params += CRM_Mailing_BAO_BouncePattern::match($body);
 135
 136         if (CRM_Mailing_Event_BAO_Bounce::create($params)) {
 137                 return civicrm_api3_create_success($params);
 138         }
 139         else {
 140                 throw new API_Exception(ts('Queue event could not be found'),'no_queue_event
 141       ');
 142         }
 143 }
 144
 145 /**
 146  * Adjust Metadata for bounce_spec action
 147  *
 148  * The metadata is used for setting defaults, documentation & validation
 149  * @param array $params array or parameters determined by getfields
 150  */
 151 function _civicrm_api3_mailing_event_bounce_spec(&$params) {
 152   $params['job_id']['api.required'] = 1;
 153   $params['job_id']['title'] = 'Job ID';
 154   $params['event_queue_id']['api.required'] = 1;
 155   $params['event_queue_id']['title'] = 'Event Queue ID';
 156   $params['hash']['api.required'] = 1;
 157   $params['hash']['title'] = 'Hash';
 158   $params['body']['api.required'] = 1;
 159   $params['body']['title'] = 'Body';
 160 }
 161
 162 /**
 163  * Handle a confirm event
 164  * @deprecated
 165  *
 166  * @param array $params
 167  *
 168  * @return array
 169  */
 170 function civicrm_api3_mailing_event_confirm($params) {
 171         return civicrm_api('mailing_event_confirm', 'create', $params);
 172 }
 173
 174 /**
 175  * @deprecated api notice
 176  * @return array of deprecated actions
 177  */
 178 function _civicrm_api3_mailing_deprecation() {
 179   return array('event_confirm' => 'Mailing api "event_confirm" action is deprecated. Use the mailing_event_confirm api instead.');
 180 }
 181
 182 /**
 183  * Handle a reply event
 184  *
 185  * @param array $params
 186  *
 187  * @return array
 188  */
 189 function civicrm_api3_mailing_event_reply($params) {
 190         $job       = $params['job_id'];
 191         $queue     = $params['event_queue_id'];
 192         $hash      = $params['hash'];
 193         $replyto   = $params['replyTo'];
 194         $bodyTxt   = CRM_Utils_Array::value('bodyTxt', $params);
 195         $bodyHTML  = CRM_Utils_Array::value('bodyHTML', $params);
 196         $fullEmail = CRM_Utils_Array::value('fullEmail', $params);
 197
 198         $mailing = CRM_Mailing_Event_BAO_Reply::reply($job, $queue, $hash, $replyto);
 199
 200         if (empty($mailing)) {
 201                 return civicrm_api3_create_error('Queue event could not be found');
 202         }
 203
 204         CRM_Mailing_Event_BAO_Reply::send($queue, $mailing, $bodyTxt, $replyto, $bodyHTML, $fullEmail);
 205
 206         return civicrm_api3_create_success($params);
 207 }
 208
 209 /**
 210  * Adjust Metadata for event_reply action
 211  *
 212  * The metadata is used for setting defaults, documentation & validation
 213  * @param array $params array or parameters determined by getfields
 214  */
 215 function _civicrm_api3_mailing_event_reply_spec(&$params) {
 216   $params['job_id']['api.required'] = 1;
 217   $params['job_id']['title'] = 'Job ID';
 218   $params['event_queue_id']['api.required'] = 1;
 219   $params['event_queue_id']['title'] = 'Event Queue ID';
 220   $params['hash']['api.required'] = 1;
 221   $params['hash']['title'] = 'Hash';
 222   $params['replyTo']['api.required'] = 0;
 223   $params['replyTo']['title'] = 'Reply To';//doesn't really explain adequately
 224 }
 225
 226 /**
 227  * Handle a forward event
 228  *
 229  * @param array $params
 230  *
 231  * @return array
 232  */
 233 function civicrm_api3_mailing_event_forward($params) {
 234         $job       = $params['job_id'];
 235         $queue     = $params['event_queue_id'];
 236         $hash      = $params['hash'];
 237         $email     = $params['email'];
 238         $fromEmail = CRM_Utils_Array::value('fromEmail', $params);
 239         $params    = CRM_Utils_Array::value('params', $params);
 240
 241         $forward = CRM_Mailing_Event_BAO_Forward::forward($job, $queue, $hash, $email, $fromEmail, $params);
 242
 243         if ($forward) {
 244                 return civicrm_api3_create_success($params);
 245         }
 246
 247         return civicrm_api3_create_error('Queue event could not be found');
 248 }
 249
 250 /**
 251  * Adjust Metadata for event_forward action
 252  *
 253  * The metadata is used for setting defaults, documentation & validation
 254  * @param array $params array or parameters determined by getfields
 255  */
 256 function _civicrm_api3_mailing_event_forward_spec(&$params) {
 257   $params['job_id']['api.required'] = 1;
 258   $params['job_id']['title'] = 'Job ID';
 259   $params['event_queue_id']['api.required'] = 1;
 260   $params['event_queue_id']['title'] = 'Event Queue ID';
 261   $params['hash']['api.required'] = 1;
 262   $params['hash']['title'] = 'Hash';
 263   $params['email']['api.required'] = 1;
 264   $params['email']['title'] = 'Forwarded to Email';
 265 }
 266
 267 /**
 268  * Handle a click event
 269  *
 270  * @param array $params
 271  *
 272  * @return array
 273  */
 274 function civicrm_api3_mailing_event_click($params) {
 275
 276         civicrm_api3_verify_mandatory($params,
 277                 'CRM_Mailing_Event_DAO_TrackableURLOpen',
 278                 array('event_queue_id', 'url_id'),
 279                 FALSE
 280         );
 281
 282         $url_id = $params['url_id'];
 283         $queue = $params['event_queue_id'];
 284
 285         $url = CRM_Mailing_Event_BAO_TrackableURLOpen::track($queue, $url_id);
 286
 287         $values             = array();
 288         $values['url']      = $url;
 289         $values['is_error'] = 0;
 290
 291         return civicrm_api3_create_success($values);
 292 }
 293
 294 /**
 295  * Handle an open event
 296  *
 297  * @param array $params
 298  *
 299  * @return array
 300  */
 301 function civicrm_api3_mailing_event_open($params) {
 302
 303         civicrm_api3_verify_mandatory($params,
 304                 'CRM_Mailing_Event_DAO_Opened',
 305                 array('event_queue_id'),
 306                 FALSE
 307         );
 308
 309         $queue = $params['event_queue_id'];
 310         $success = CRM_Mailing_Event_BAO_Opened::open($queue);
 311
 312         if (!$success) {
 313                 return civicrm_api3_create_error('mailing open event failed');
 314         }
 315
 316         return civicrm_api3_create_success($params);
 317 }
 318
 319 function civicrm_api3_mailing_preview($params) {
 320   civicrm_api3_verify_mandatory($params,
 321     'CRM_Mailing_DAO_Mailing',
 322     array('id'),
 323     FALSE
 324   );
 325
 326   $fromEmail = NULL;
 327   if (!empty($params['from_email'])) {
 328     $fromEmail = $params['from_email'];
 329   }
 330
 331   $session = CRM_Core_Session::singleton();
 332   $mailing = new CRM_Mailing_BAO_Mailing();
 333   $mailing->id = $params['id'];
 334   $mailing->find(TRUE);
 335
 336   CRM_Mailing_BAO_Mailing::tokenReplace($mailing);
 337
 338   // get and format attachments
 339   $attachments = CRM_Core_BAO_File::getEntityFile('civicrm_mailing', $mailing->id);
 340
 341   $returnProperties = $mailing->getReturnProperties();
 342   $contactID = CRM_Utils_Array::value('contact_id', $params);
 343   if (!$contactID) {
 344     $contactID = $session->get('userID');
 345   }
 346   $mailingParams = array('contact_id' => $contactID);
 347
 348   $details = CRM_Utils_Token::getTokenDetails($mailingParams, $returnProperties, TRUE, TRUE, NULL, $mailing->getFlattenedTokens());
 349
 350   $mime = &$mailing->compose(NULL, NULL, NULL, $session->get('userID'), $fromEmail, $fromEmail,
 351     TRUE, $details[0][$contactID], $attachments
 352   );
 353
 354   return civicrm_api3_create_success(array('subject' => $mime->_headers['Subject'], 'html' => $mime->getHTMLBody(), 'text' => $mime->getTXTBody()));
 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   while (!$isComplete) {
 424     $isComplete = CRM_Mailing_BAO_MailingJob::runJobs($testEmailParams);
 425   }
 426
 427   //return delivered mail info
 428   $mailDelivered = CRM_Mailing_Event_BAO_Delivered::getRows($params['mailing_id'], $job['id'], TRUE, NULL, NULL, NULL, TRUE);
 429
 430   return civicrm_api3_create_success($mailDelivered);
 431 }
 432
 433 /**
 434  * Adjust Metadata for send_mail action
 435  *
 436  * The metadata is used for setting defaults, documentation & validation
 437  * @param array $params array or parameters determined by getfields
 438  */
 439 function _civicrm_api3_mailing_stats_spec(&$params) {
 440   $params['date']['api.default'] = 'now';
 441 }
 442
 443 function civicrm_api3_mailing_stats($params) {
 444   civicrm_api3_verify_mandatory($params,
 445     'CRM_Mailing_DAO_MailingJob',
 446     array('mailing_id'),
 447     FALSE
 448   );
 449
 450   if ($params['date'] == 'now') {
 451     $params['date'] = date('YmdHis');
 452   }
 453   else {
 454     $params['date'] = CRM_Utils_Date::processDate($params['date'] . ' ' . $params['date_time']);
 455   }
 456
 457   $stats[$params['mailing_id']] = array();
 458   if (empty($params['job_id'])) {
 459     $params['job_id'] = NULL;
 460   }
 461   foreach (array('Delivered', 'Bounces', 'Unsubscribers', 'Unique Clicks', 'Opened') as $detail) {
 462     switch ($detail) {
 463       case 'Delivered':
 464         $stats[$params['mailing_id']] += array(
 465           $detail =>  CRM_Mailing_Event_BAO_Delivered::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date'])
 466         );
 467         break;
 468       case 'Bounces':
 469         $stats[$params['mailing_id']] += array(
 470           $detail =>  CRM_Mailing_Event_BAO_Bounce::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date'])
 471         );
 472         break;
 473       case 'Unsubscribers':
 474         $stats[$params['mailing_id']] += array(
 475           $detail =>  CRM_Mailing_Event_BAO_Unsubscribe::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, NULL, $params['date'])
 476         );
 477         break;
 478       case 'Unique Clicks':
 479         $stats[$params['mailing_id']] += array(
 480           $detail =>  CRM_Mailing_Event_BAO_TrackableURLOpen::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, NULL, $params['date'])
 481         );
 482         break;
 483       case 'Opened':
 484         $stats[$params['mailing_id']] += array(
 485           $detail =>  CRM_Mailing_Event_BAO_Opened::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date'])
 486         );
 487         break;
 488     }
 489   }
 490   return civicrm_api3_create_success($stats);
 491 }
 492
 493 /**
 494  * Fix the reset dates on the email record based on when a mail was last delivered
 495  * We only consider mailings that were completed and finished in the last 3 to 7 days
 496  * Both the min and max days can be set via the params
 497  */
 498 function civicrm_api3_mailing_update_email_resetdate($params) {
 499         CRM_Mailing_Event_BAO_Delivered::updateEmailResetDate(
 500                 CRM_Utils_Array::value('minDays', $params, 3),
 501                 CRM_Utils_Array::value('maxDays', $params, 3)
 502         );
 503         return civicrm_api3_create_success();
 504 }