4 +--------------------------------------------------------------------+
5 | CiviCRM version 4.6 |
6 +--------------------------------------------------------------------+
7 | Copyright CiviCRM LLC (c) 2004-2014 |
8 +--------------------------------------------------------------------+
9 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
31 * APIv3 functions for registering/processing mailing events.
33 * @package CiviCRM_APIv3
34 * @subpackage API_Mailing
35 * @copyright CiviCRM LLC (c) 2004-2014
41 * Handle a create event.
43 * @param array $params
49 function civicrm_api3_mailing_create($params, $ids = array()) {
50 if (CRM_Mailing_Info
::workflowEnabled()) {
51 if (!CRM_Core_Permission
::check('create mailings')) {
52 throw new \Civi\API\Exception\
UnauthorizedException("This system uses advanced CiviMail workflows which require additional permissions");
54 if (!CRM_Core_Permission
::check('schedule mailings')) {
55 unset($params['scheduled_date']);
56 unset($params['scheduled_id']);
58 if (!CRM_Core_Permission
::check('approve mailings')) {
59 unset($params['approval_date']);
60 unset($params['approver_id']);
61 unset($params['approval_status_id']);
62 unset($params['approval_note']);
65 return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
68 function civicrm_api3_mailing_get_token($params) {
69 if (!array_key_exists("usage", $params)) {
70 throw new API_Exception('Mandatory keys missing from params array: entity');
73 $tokens = CRM_Core_SelectValues
::contactTokens();
74 switch ($params['usage']) {
76 $tokens = array_merge(CRM_Core_SelectValues
::mailingTokens(), $tokens);
79 case 'ScheduleEventReminder':
80 $tokens = array_merge(CRM_Core_SelectValues
::activityTokens(), $tokens);
81 $tokens = array_merge(CRM_Core_SelectValues
::eventTokens(), $tokens);
82 $tokens = array_merge(CRM_Core_SelectValues
::membershipTokens(), $tokens);
85 case 'ManageEventScheduleReminder':
86 $tokens = array_merge(CRM_Core_SelectValues
::eventTokens(), $tokens);
90 return CRM_Utils_Token
::formatTokensForDisplay($tokens);
94 * Adjust Metadata for Create action
96 * The metadata is used for setting defaults, documentation & validation
97 * @param array $params
98 * Array or parameters determined by getfields.
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?';
110 * Handle a delete event.
112 * @param array $params
118 function civicrm_api3_mailing_delete($params, $ids = array()) {
119 return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
123 * Handle a get event.
125 * @param array $params
128 function civicrm_api3_mailing_get($params) {
129 return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
132 function _civicrm_api3_mailing_submit_spec(&$spec) {
133 $mailingFields = CRM_Mailing_DAO_Mailing
::fields();
134 $spec['id'] = $mailingFields['id'];
135 $spec['scheduled_date'] = $mailingFields['scheduled_date'];
136 $spec['approval_date'] = $mailingFields['approval_date'];
137 $spec['approval_status_id'] = $mailingFields['approval_status_id'];
138 $spec['approval_note'] = $mailingFields['approval_note'];
139 // _skip_evil_bao_auto_recipients_: bool
143 * @param array $params
145 * @throws API_Exception
147 function civicrm_api3_mailing_submit($params) {
148 civicrm_api3_verify_mandatory($params, 'CRM_Mailing_DAO_Mailing', array('id'));
150 if (!isset($params['scheduled_date']) && !isset($updateParams['approval_date'])) {
151 throw new API_Exception("Missing parameter scheduled_date and/or approval_date");
153 if (!is_numeric(CRM_Core_Session
::getLoggedInContactID())) {
154 throw new API_Exception("Failed to determine current user");
157 $updateParams = array();
158 $updateParams['id'] = $params['id'];
160 // the BAO will autocreate the job
161 $updateParams['api.mailing_job.create'] = 0; // note: exact match to API default
163 // note: we'll pass along scheduling/approval fields, but they may get ignored
164 // if we don't have permission
165 if (isset($params['scheduled_date'])) {
166 $updateParams['scheduled_date'] = $params['scheduled_date'];
167 $updateParams['scheduled_id'] = CRM_Core_Session
::getLoggedInContactID();
169 if (isset($params['approval_date'])) {
170 $updateParams['approval_date'] = $params['approval_date'];
171 $updateParams['approver_id'] = CRM_Core_Session
::getLoggedInContactID();
172 $updateParams['approval_status_id'] = CRM_Utils_Array
::value('approval_status_id', $updateParams, CRM_Core_OptionGroup
::getDefaultValue('mail_approval_status'));
174 if (isset($params['approval_note'])) {
175 $updateParams['approval_note'] = $params['approval_note'];
177 if (isset($params['_skip_evil_bao_auto_recipients_'])) {
178 $updateParams['_skip_evil_bao_auto_recipients_'] = $params['_skip_evil_bao_auto_recipients_'];
181 $updateParams['options']['reload'] = 1;
182 return civicrm_api3('Mailing', 'create', $updateParams);
186 * Process a bounce event by passing through to the BAOs.
188 * @param array $params
190 * @throws API_Exception
193 function civicrm_api3_mailing_event_bounce($params) {
194 $body = $params['body'];
195 unset($params['body']);
197 $params +
= CRM_Mailing_BAO_BouncePattern
::match($body);
199 if (CRM_Mailing_Event_BAO_Bounce
::create($params)) {
200 return civicrm_api3_create_success($params);
203 throw new API_Exception(ts('Queue event could not be found'),'no_queue_event
209 * Adjust Metadata for bounce_spec action
211 * The metadata is used for setting defaults, documentation & validation
212 * @param array $params
213 * Array or parameters determined by getfields.
215 function _civicrm_api3_mailing_event_bounce_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['body']['api.required'] = 1;
223 $params['body']['title'] = 'Body';
227 * Handle a confirm event
230 * @param array $params
234 function civicrm_api3_mailing_event_confirm($params) {
235 return civicrm_api('mailing_event_confirm', 'create', $params);
239 * @deprecated api notice
241 * Array of deprecated actions
243 function _civicrm_api3_mailing_deprecation() {
244 return array('event_confirm' => 'Mailing api "event_confirm" action is deprecated. Use the mailing_event_confirm api instead.');
248 * Handle a reply event
250 * @param array $params
254 function civicrm_api3_mailing_event_reply($params) {
255 $job = $params['job_id'];
256 $queue = $params['event_queue_id'];
257 $hash = $params['hash'];
258 $replyto = $params['replyTo'];
259 $bodyTxt = CRM_Utils_Array
::value('bodyTxt', $params);
260 $bodyHTML = CRM_Utils_Array
::value('bodyHTML', $params);
261 $fullEmail = CRM_Utils_Array
::value('fullEmail', $params);
263 $mailing = CRM_Mailing_Event_BAO_Reply
::reply($job, $queue, $hash, $replyto);
265 if (empty($mailing)) {
266 return civicrm_api3_create_error('Queue event could not be found');
269 CRM_Mailing_Event_BAO_Reply
::send($queue, $mailing, $bodyTxt, $replyto, $bodyHTML, $fullEmail);
271 return civicrm_api3_create_success($params);
275 * Adjust Metadata for event_reply action
277 * The metadata is used for setting defaults, documentation & validation
278 * @param array $params
279 * Array or parameters determined by getfields.
281 function _civicrm_api3_mailing_event_reply_spec(&$params) {
282 $params['job_id']['api.required'] = 1;
283 $params['job_id']['title'] = 'Job ID';
284 $params['event_queue_id']['api.required'] = 1;
285 $params['event_queue_id']['title'] = 'Event Queue ID';
286 $params['hash']['api.required'] = 1;
287 $params['hash']['title'] = 'Hash';
288 $params['replyTo']['api.required'] = 0;
289 $params['replyTo']['title'] = 'Reply To';//doesn't really explain adequately
293 * Handle a forward event
295 * @param array $params
299 function civicrm_api3_mailing_event_forward($params) {
300 $job = $params['job_id'];
301 $queue = $params['event_queue_id'];
302 $hash = $params['hash'];
303 $email = $params['email'];
304 $fromEmail = CRM_Utils_Array
::value('fromEmail', $params);
305 $params = CRM_Utils_Array
::value('params', $params);
307 $forward = CRM_Mailing_Event_BAO_Forward
::forward($job, $queue, $hash, $email, $fromEmail, $params);
310 return civicrm_api3_create_success($params);
313 return civicrm_api3_create_error('Queue event could not be found');
317 * Adjust Metadata for event_forward action
319 * The metadata is used for setting defaults, documentation & validation
320 * @param array $params
321 * Array or parameters determined by getfields.
323 function _civicrm_api3_mailing_event_forward_spec(&$params) {
324 $params['job_id']['api.required'] = 1;
325 $params['job_id']['title'] = 'Job ID';
326 $params['event_queue_id']['api.required'] = 1;
327 $params['event_queue_id']['title'] = 'Event Queue ID';
328 $params['hash']['api.required'] = 1;
329 $params['hash']['title'] = 'Hash';
330 $params['email']['api.required'] = 1;
331 $params['email']['title'] = 'Forwarded to Email';
335 * Handle a click event
337 * @param array $params
341 function civicrm_api3_mailing_event_click($params) {
342 civicrm_api3_verify_mandatory($params,
343 'CRM_Mailing_Event_DAO_TrackableURLOpen',
344 array('event_queue_id', 'url_id'),
348 $url_id = $params['url_id'];
349 $queue = $params['event_queue_id'];
351 $url = CRM_Mailing_Event_BAO_TrackableURLOpen
::track($queue, $url_id);
354 $values['url'] = $url;
355 $values['is_error'] = 0;
357 return civicrm_api3_create_success($values);
361 * Handle an open event
363 * @param array $params
367 function civicrm_api3_mailing_event_open($params) {
369 civicrm_api3_verify_mandatory($params,
370 'CRM_Mailing_Event_DAO_Opened',
371 array('event_queue_id'),
375 $queue = $params['event_queue_id'];
376 $success = CRM_Mailing_Event_BAO_Opened
::open($queue);
379 return civicrm_api3_create_error('mailing open event failed');
382 return civicrm_api3_create_success($params);
385 function civicrm_api3_mailing_preview($params) {
386 civicrm_api3_verify_mandatory($params,
387 'CRM_Mailing_DAO_Mailing',
393 if (!empty($params['from_email'])) {
394 $fromEmail = $params['from_email'];
397 $session = CRM_Core_Session
::singleton();
398 $mailing = new CRM_Mailing_BAO_Mailing();
399 $mailing->id
= $params['id'];
400 $mailing->find(TRUE);
402 CRM_Mailing_BAO_Mailing
::tokenReplace($mailing);
404 // get and format attachments
405 $attachments = CRM_Core_BAO_File
::getEntityFile('civicrm_mailing', $mailing->id
);
407 $returnProperties = $mailing->getReturnProperties();
408 $contactID = CRM_Utils_Array
::value('contact_id', $params);
410 $contactID = $session->get('userID');
412 $mailingParams = array('contact_id' => $contactID);
414 $details = CRM_Utils_Token
::getTokenDetails($mailingParams, $returnProperties, TRUE, TRUE, NULL, $mailing->getFlattenedTokens());
416 $mime = &$mailing->compose(NULL, NULL, NULL, $session->get('userID'), $fromEmail, $fromEmail,
417 TRUE, $details[0][$contactID], $attachments
420 return civicrm_api3_create_success(array(
421 'id' => $params['id'],
422 'contact_id' => $contactID,
423 'subject' => $mime->_headers
['Subject'],
424 'body_html' => $mime->getHTMLBody(),
425 'body_text' => $mime->getTXTBody(),
429 function _civicrm_api3_mailing_send_test_spec(&$spec) {
430 $spec['test_group']['title'] = 'Test Group ID';
431 $spec['test_email']['title'] = 'Test Email Address';
434 function civicrm_api3_mailing_send_test($params) {
435 if (!array_key_exists('test_group', $params) && !array_key_exists('test_email', $params)) {
436 throw new API_Exception("Mandatory key(s) missing from params array: test_group and/or test_email field are required");
438 civicrm_api3_verify_mandatory($params,
439 'CRM_Mailing_DAO_MailingJob',
444 $testEmailParams = _civicrm_api3_generic_replace_base_params($params);
445 $testEmailParams['is_test'] = 1;
446 $job = civicrm_api3('MailingJob', 'create', $testEmailParams);
447 $testEmailParams['job_id'] = $job['id'];
448 $testEmailParams['emails'] = explode(',', $testEmailParams['test_email']);
449 if (!empty($params['test_email'])) {
450 $query = CRM_Utils_SQL_Select
::from('civicrm_email e')
451 ->select(array('e.id', 'e.contact_id', 'e.email'))
452 ->join('c', 'INNER JOIN civicrm_contact c ON e.contact_id = c.id')
453 ->where('e.email IN (@emails)', array('@emails' => $testEmailParams['emails']))
454 ->where('e.on_hold = 0')
455 ->where('c.is_opt_out = 0')
456 ->where('c.do_not_email = 0')
457 ->where('c.is_deceased = 0')
459 ->orderBy(array('e.is_bulkmail DESC', 'e.is_primary DESC'))
461 $dao = CRM_Core_DAO
::executeQuery($query);
462 $emailDetail = array();
463 // fetch contact_id and email id for all existing emails
464 while ($dao->fetch()) {
465 $emailDetail[$dao->email
] = array(
466 'contact_id' => $dao->contact_id
,
467 'email_id' => $dao->id
,
471 foreach ($testEmailParams['emails'] as $key => $email) {
472 $email = trim($email);
473 $contactId = $emailId = NULL;
474 if (array_key_exists($email, $emailDetail)) {
475 $emailId = $emailDetail[$email]['email_id'];
476 $contactId = $emailDetail[$email]['contact_id'];
479 //create new contact.
480 $contact = civicrm_api3('Contact', 'create',
482 'contact_type' => 'Individual',
484 'api.Email.get' => array('return' => 'id'),
487 $contactId = $contact['id'];
488 $emailId = $contact['values'][$contactId]['api.Email.get']['id'];
490 civicrm_api3('MailingEventQueue', 'create',
492 'job_id' => $job['id'],
493 'email_id' => $emailId,
494 'contact_id' => $contactId,
501 $config = CRM_Core_Config
::singleton();
502 $mailerJobSize = (property_exists($config, 'mailerJobSize')) ?
$config->mailerJobSize
: NULL;
503 while (!$isComplete) {
504 // Q: In CRM_Mailing_BAO_Mailing::processQueue(), the three runJobs*()
505 // functions are all called. Why does Mailing.send_test only call one?
506 // CRM_Mailing_BAO_MailingJob::runJobs_pre($mailerJobSize, NULL);
507 $isComplete = CRM_Mailing_BAO_MailingJob
::runJobs($testEmailParams);
508 // CRM_Mailing_BAO_MailingJob::runJobs_post(NULL);
511 //return delivered mail info
512 $mailDelivered = CRM_Mailing_Event_BAO_Delivered
::getRows($params['mailing_id'], $job['id'], TRUE, NULL, NULL, NULL, TRUE);
514 return civicrm_api3_create_success($mailDelivered);
518 * Adjust Metadata for send_mail action
520 * The metadata is used for setting defaults, documentation & validation
521 * @param array $params
522 * Array or parameters determined by getfields.
524 function _civicrm_api3_mailing_stats_spec(&$params) {
525 $params['date']['api.default'] = 'now';
526 $params['date']['title'] = 'Date';
529 function civicrm_api3_mailing_stats($params) {
530 civicrm_api3_verify_mandatory($params,
531 'CRM_Mailing_DAO_MailingJob',
536 if ($params['date'] == 'now') {
537 $params['date'] = date('YmdHis');
540 $params['date'] = CRM_Utils_Date
::processDate($params['date'] . ' ' . $params['date_time']);
543 $stats[$params['mailing_id']] = array();
544 if (empty($params['job_id'])) {
545 $params['job_id'] = NULL;
547 foreach (array('Delivered', 'Bounces', 'Unsubscribers', 'Unique Clicks', 'Opened') as $detail) {
550 $stats[$params['mailing_id']] +
= array(
551 $detail => CRM_Mailing_Event_BAO_Delivered
::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date']),
556 $stats[$params['mailing_id']] +
= array(
557 $detail => CRM_Mailing_Event_BAO_Bounce
::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date']),
561 case 'Unsubscribers':
562 $stats[$params['mailing_id']] +
= array(
563 $detail => CRM_Mailing_Event_BAO_Unsubscribe
::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, NULL, $params['date']),
567 case 'Unique Clicks':
568 $stats[$params['mailing_id']] +
= array(
569 $detail => CRM_Mailing_Event_BAO_TrackableURLOpen
::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, NULL, $params['date']),
574 $stats[$params['mailing_id']] +
= array(
575 $detail => CRM_Mailing_Event_BAO_Opened
::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date']),
580 return civicrm_api3_create_success($stats);
584 * Fix the reset dates on the email record based on when a mail was last delivered
585 * We only consider mailings that were completed and finished in the last 3 to 7 days
586 * Both the min and max days can be set via the params
588 function civicrm_api3_mailing_update_email_resetdate($params) {
589 CRM_Mailing_Event_BAO_Delivered
::updateEmailResetDate(
590 CRM_Utils_Array
::value('minDays', $params, 3),
591 CRM_Utils_Array
::value('maxDays', $params, 3)
593 return civicrm_api3_create_success();