api/v3/Mailing.php

   1 <?php
   2 // $Id$
   3
   4 /*
   5  +--------------------------------------------------------------------+
   6  | CiviCRM version 4.3                                                |
   7  +--------------------------------------------------------------------+
   8  | Copyright CiviCRM LLC (c) 2004-2013                                |
   9  +--------------------------------------------------------------------+
  10  | This file is a part of CiviCRM.                                    |
  11  |                                                                    |
  12  | CiviCRM is free software; you can copy, modify, and distribute it  |
  13  | under the terms of the GNU Affero General Public License           |
  14  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  15  |                                                                    |
  16  | CiviCRM is distributed in the hope that it will be useful, but     |
  17  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  18  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  19  | See the GNU Affero General Public License for more details.        |
  20  |                                                                    |
  21  | You should have received a copy of the GNU Affero General Public   |
  22  | License and the CiviCRM Licensing Exception along                  |
  23  | with this program; if not, contact CiviCRM LLC                     |
  24  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  25  | GNU Affero General Public License or the licensing of CiviCRM,     |
  26  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  27  +--------------------------------------------------------------------+
  28 */
  29
  30 /**
  31  *
  32  * APIv3 functions for registering/processing mailing events.
  33  *
  34  * @package CiviCRM_APIv3
  35  * @subpackage API_Mailing
  36  * @copyright CiviCRM LLC (c) 2004-2013
  37  * $Id$
  38  *
  39  */
  40
  41 /**
  42  * Files required for this package
  43  */
  44
  45 /**
  46  * Handle a create event.
  47  *
  48  * @param array $params
  49  * @return array API Success Array
  50  */
  51 function civicrm_api3_mailing_create($params, $ids = array()) {
  52   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  53 }
  54
  55 /**
  56  * Adjust Metadata for Create action
  57  *
  58  * The metadata is used for setting defaults, documentation & validation
  59  * @param array $params array or parameters determined by getfields
  60  */
  61 function _civicrm_api3_mailing_create_spec(&$params) {
  62   $params['name']['api.required'] = 1;
  63   $params['subject']['api.required'] = 1;
  64   // should be able to default to 'user_contact_id' & have it work but it didn't work in test so
  65   // making required for simplicity
  66   $params['created_id']['api.required'] = 1;
  67   $params['api.mailing_job.create']['api.default'] = 1;
  68 }
  69
  70 /**
  71  * Handle a get event.
  72  *
  73  * @param array $params
  74  * @return array
  75  */
  76 function civicrm_api3_mailing_get($params, $ids = array()) {
  77   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  78 }
  79
  80 /**
  81  * Process a bounce event by passing through to the BAOs.
  82  *
  83  * @param array $params
  84  *
  85  * @return array
  86  */
  87 function civicrm_api3_mailing_event_bounce($params) {
  88
  89   $body = $params['body'];
  90   unset($params['body']);
  91
  92   $params += CRM_Mailing_BAO_BouncePattern::match($body);
  93
  94   if (CRM_Mailing_Event_BAO_Bounce::create($params)) {
  95     return civicrm_api3_create_success($params);
  96   }
  97   else {
  98     throw new API_Exception(ts('Queue event could not be found'),'no_queue_event
  99       ');
 100   }
 101 }
 102
 103 /**
 104  * Adjust Metadata for bounce_spec action
 105  *
 106  * The metadata is used for setting defaults, documentation & validation
 107  * @param array $params array or parameters determined by getfields
 108  */
 109 function _civicrm_api3_mailing_event_bounce_spec(&$params) {
 110   $params['job_id']['api.required'] = 1;
 111   $params['event_queue_id']['api.required'] = 1;
 112   $params['hash']['api.required'] = 1;
 113   $params['body']['api.required'] = 1;
 114 }
 115
 116 /**
 117  * Handle a confirm event
 118  * @deprecated
 119  *
 120  * @param array $params
 121  *
 122  * @return array
 123  */
 124 function civicrm_api3_mailing_event_confirm($params) {
 125   return civicrm_api('mailing_event_confirm', 'create', $params);
 126 }
 127
 128 /**
 129  * Handle a reply event
 130  *
 131  * @param array $params
 132  *
 133  * @return array
 134  */
 135 function civicrm_api3_mailing_event_reply($params) {
 136   $job       = $params['job_id'];
 137   $queue     = $params['event_queue_id'];
 138   $hash      = $params['hash'];
 139   $replyto   = $params['replyTo'];
 140   $bodyTxt   = CRM_Utils_Array::value('bodyTxt', $params);
 141   $bodyHTML  = CRM_Utils_Array::value('bodyHTML', $params);
 142   $fullEmail = CRM_Utils_Array::value('fullEmail', $params);
 143
 144   $mailing = CRM_Mailing_Event_BAO_Reply::reply($job, $queue, $hash, $replyto);
 145
 146   if (empty($mailing)) {
 147     return civicrm_api3_create_error('Queue event could not be found');
 148   }
 149
 150   CRM_Mailing_Event_BAO_Reply::send($queue, $mailing, $bodyTxt, $replyto, $bodyHTML, $fullEmail);
 151
 152   return civicrm_api3_create_success($params);
 153 }
 154
 155 /**
 156  * Adjust Metadata for event_reply action
 157  *
 158  * The metadata is used for setting defaults, documentation & validation
 159  * @param array $params array or parameters determined by getfields
 160  */
 161 function _civicrm_api3_mailing_event_reply_spec(&$params) {
 162   $params['job_id']['api.required'] = 1;
 163   $params['event_queue_id']['api.required'] = 1;
 164   $params['hash']['api.required'] = 1;
 165   $params['replyTo']['api.required'] = 1;
 166 }
 167
 168 /**
 169  * Handle a forward event
 170  *
 171  * @param array $params
 172  *
 173  * @return array
 174  */
 175 function civicrm_api3_mailing_event_forward($params) {
 176   $job       = $params['job_id'];
 177   $queue     = $params['event_queue_id'];
 178   $hash      = $params['hash'];
 179   $email     = $params['email'];
 180   $fromEmail = CRM_Utils_Array::value('fromEmail', $params);
 181   $params    = CRM_Utils_Array::value('params', $params);
 182
 183   $forward = CRM_Mailing_Event_BAO_Forward::forward($job, $queue, $hash, $email, $fromEmail, $params);
 184
 185   if ($forward) {
 186     return civicrm_api3_create_success($params);
 187   }
 188
 189   return civicrm_api3_create_error('Queue event could not be found');
 190 }
 191
 192 /**
 193  * Adjust Metadata for event_forward action
 194  *
 195  * The metadata is used for setting defaults, documentation & validation
 196  * @param array $params array or parameters determined by getfields
 197  */
 198 function _civicrm_api3_mailing_event_forward_spec(&$params) {
 199   $params['job_id']['api.required'] = 1;
 200   $params['event_queue_id']['api.required'] = 1;
 201   $params['hash']['api.required'] = 1;
 202   $params['email']['api.required'] = 1;
 203 }
 204
 205 /**
 206  * Handle a click event
 207  *
 208  * @param array $params
 209  *
 210  * @return array
 211  */
 212 function civicrm_api3_mailing_event_click($params) {
 213
 214   civicrm_api3_verify_mandatory($params,
 215     'CRM_Mailing_Event_DAO_TrackableURLOpen',
 216     array('event_queue_id', 'url_id'),
 217     FALSE
 218   );
 219
 220   $url_id = $params['url_id'];
 221   $queue = $params['event_queue_id'];
 222
 223   $url = CRM_Mailing_Event_BAO_TrackableURLOpen::track($queue, $url_id);
 224
 225   $values             = array();
 226   $values['url']      = $url;
 227   $values['is_error'] = 0;
 228
 229   return civicrm_api3_create_success($values);
 230 }
 231
 232 /**
 233  * Handle an open event
 234  *
 235  * @param array $params
 236  *
 237  * @return array
 238  */
 239 function civicrm_api3_mailing_event_open($params) {
 240
 241   civicrm_api3_verify_mandatory($params,
 242     'CRM_Mailing_Event_DAO_Opened',
 243     array('event_queue_id'),
 244     FALSE
 245   );
 246
 247   $queue = $params['event_queue_id'];
 248   $success = CRM_Mailing_Event_BAO_Opened::open($queue);
 249
 250   if (!$success) {
 251     return civicrm_api3_create_error('mailing open event failed');
 252   }
 253
 254   return civicrm_api3_create_success($params);
 255 }
 256
 257 /**
 258  * Fix the reset dates on the email record based on when a mail was last delivered
 259  * We only consider mailings that were completed and finished in the last 3 to 7 days
 260  * Both the min and max days can be set via the params
 261  */
 262 function civicrm_api3_mailing_update_email_resetdate($params) {
 263   CRM_Mailing_Event_BAO_Delivered::updateEmailResetDate(
 264     CRM_Utils_Array::value('minDays', $params, 3),
 265     CRM_Utils_Array::value('maxDays', $params, 3)
 266   );
 267   return civicrm_api3_create_success();
 268 }
 269
 270