3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.6 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2014 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
30 * APIv3 functions for registering/processing mailing events.
32 * @package CiviCRM_APIv3
36 * Handle a create event.
38 * @param array $params
42 * @throws \API_Exception
43 * @throws \Civi\API\Exception\UnauthorizedException
45 function civicrm_api3_mailing_create($params) {
46 if (CRM_Mailing_Info
::workflowEnabled()) {
47 if (!CRM_Core_Permission
::check('create mailings')) {
48 throw new \Civi\API\Exception\
UnauthorizedException("This system uses advanced CiviMail workflows which require additional permissions");
50 if (!CRM_Core_Permission
::check('schedule mailings')) {
51 unset($params['scheduled_date']);
52 unset($params['scheduled_id']);
54 if (!CRM_Core_Permission
::check('approve mailings')) {
55 unset($params['approval_date']);
56 unset($params['approver_id']);
57 unset($params['approval_status_id']);
58 unset($params['approval_note']);
61 return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
67 * @param array $params
70 * @throws \API_Exception
72 function civicrm_api3_mailing_get_token($params) {
73 if (!array_key_exists("usage", $params)) {
74 throw new API_Exception('Mandatory keys missing from params array: entity');
77 $tokens = CRM_Core_SelectValues
::contactTokens();
78 switch ($params['usage']) {
80 $tokens = array_merge(CRM_Core_SelectValues
::mailingTokens(), $tokens);
83 case 'ScheduleEventReminder':
84 $tokens = array_merge(CRM_Core_SelectValues
::activityTokens(), $tokens);
85 $tokens = array_merge(CRM_Core_SelectValues
::eventTokens(), $tokens);
86 $tokens = array_merge(CRM_Core_SelectValues
::membershipTokens(), $tokens);
89 case 'ManageEventScheduleReminder':
90 $tokens = array_merge(CRM_Core_SelectValues
::eventTokens(), $tokens);
94 return CRM_Utils_Token
::formatTokensForDisplay($tokens);
98 * Adjust Metadata for Create action.
100 * The metadata is used for setting defaults, documentation & validation.
102 * @param array $params
103 * Array of parameters determined by getfields.
105 function _civicrm_api3_mailing_create_spec(&$params) {
106 $params['created_id']['api.required'] = 1;
107 $params['created_id']['api.default'] = 'user_contact_id';
108 $params['api.mailing_job.create']['api.default'] = 1;
109 $params['api.mailing_job.create']['title'] = 'Schedule Mailing?';
113 * Handle a delete event.
115 * @param array $params
120 function civicrm_api3_mailing_delete($params) {
121 return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
125 * Handle a get event.
127 * @param array $params
131 function civicrm_api3_mailing_get($params) {
132 return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
136 * Adjust metadata for mailing submit api function.
140 function _civicrm_api3_mailing_submit_spec(&$spec) {
141 $mailingFields = CRM_Mailing_DAO_Mailing
::fields();
142 $spec['id'] = $mailingFields['id'];
143 $spec['scheduled_date'] = $mailingFields['scheduled_date'];
144 $spec['approval_date'] = $mailingFields['approval_date'];
145 $spec['approval_status_id'] = $mailingFields['approval_status_id'];
146 $spec['approval_note'] = $mailingFields['approval_note'];
147 // _skip_evil_bao_auto_recipients_: bool
153 * @param array $params
156 * @throws API_Exception
158 function civicrm_api3_mailing_submit($params) {
159 civicrm_api3_verify_mandatory($params, 'CRM_Mailing_DAO_Mailing', array('id'));
161 if (!isset($params['scheduled_date']) && !isset($updateParams['approval_date'])) {
162 throw new API_Exception("Missing parameter scheduled_date and/or approval_date");
164 if (!is_numeric(CRM_Core_Session
::getLoggedInContactID())) {
165 throw new API_Exception("Failed to determine current user");
168 $updateParams = array();
169 $updateParams['id'] = $params['id'];
171 // The BAO will auto-create the job - note: exact match to API default.
172 $updateParams['api.mailing_job.create'] = 0;
174 // Note: we'll pass along scheduling/approval fields, but they may get ignored
175 // if we don't have permission.
176 if (isset($params['scheduled_date'])) {
177 $updateParams['scheduled_date'] = $params['scheduled_date'];
178 $updateParams['scheduled_id'] = CRM_Core_Session
::getLoggedInContactID();
180 if (isset($params['approval_date'])) {
181 $updateParams['approval_date'] = $params['approval_date'];
182 $updateParams['approver_id'] = CRM_Core_Session
::getLoggedInContactID();
183 $updateParams['approval_status_id'] = CRM_Utils_Array
::value('approval_status_id', $updateParams, CRM_Core_OptionGroup
::getDefaultValue('mail_approval_status'));
185 if (isset($params['approval_note'])) {
186 $updateParams['approval_note'] = $params['approval_note'];
188 if (isset($params['_skip_evil_bao_auto_recipients_'])) {
189 $updateParams['_skip_evil_bao_auto_recipients_'] = $params['_skip_evil_bao_auto_recipients_'];
192 $updateParams['options']['reload'] = 1;
193 return civicrm_api3('Mailing', 'create', $updateParams);
197 * Process a bounce event by passing through to the BAOs.
199 * @param array $params
201 * @throws API_Exception
204 function civicrm_api3_mailing_event_bounce($params) {
205 $body = $params['body'];
206 unset($params['body']);
208 $params +
= CRM_Mailing_BAO_BouncePattern
::match($body);
210 if (CRM_Mailing_Event_BAO_Bounce
::create($params)) {
211 return civicrm_api3_create_success($params);
214 throw new API_Exception(ts('Queue event could not be found'), 'no_queue_event
220 * Adjust Metadata for bounce_spec action.
222 * The metadata is used for setting defaults, documentation & validation.
224 * @param array $params
225 * Array of parameters determined by getfields.
227 function _civicrm_api3_mailing_event_bounce_spec(&$params) {
228 $params['job_id']['api.required'] = 1;
229 $params['job_id']['title'] = 'Job ID';
230 $params['event_queue_id']['api.required'] = 1;
231 $params['event_queue_id']['title'] = 'Event Queue ID';
232 $params['hash']['api.required'] = 1;
233 $params['hash']['title'] = 'Hash';
234 $params['body']['api.required'] = 1;
235 $params['body']['title'] = 'Body';
239 * Handle a confirm event.
243 * @param array $params
247 function civicrm_api3_mailing_event_confirm($params) {
248 return civicrm_api('mailing_event_confirm', 'create', $params);
252 * Declare deprecated functions.
254 * @deprecated api notice
256 * Array of deprecated actions
258 function _civicrm_api3_mailing_deprecation() {
259 return array('event_confirm' => 'Mailing api "event_confirm" action is deprecated. Use the mailing_event_confirm api instead.');
263 * Handle a reply event.
265 * @param array $params
269 function civicrm_api3_mailing_event_reply($params) {
270 $job = $params['job_id'];
271 $queue = $params['event_queue_id'];
272 $hash = $params['hash'];
273 $replyto = $params['replyTo'];
274 $bodyTxt = CRM_Utils_Array
::value('bodyTxt', $params);
275 $bodyHTML = CRM_Utils_Array
::value('bodyHTML', $params);
276 $fullEmail = CRM_Utils_Array
::value('fullEmail', $params);
278 $mailing = CRM_Mailing_Event_BAO_Reply
::reply($job, $queue, $hash, $replyto);
280 if (empty($mailing)) {
281 return civicrm_api3_create_error('Queue event could not be found');
284 CRM_Mailing_Event_BAO_Reply
::send($queue, $mailing, $bodyTxt, $replyto, $bodyHTML, $fullEmail);
286 return civicrm_api3_create_success($params);
290 * Adjust Metadata for event_reply action.
292 * The metadata is used for setting defaults, documentation & validation.
294 * @param array $params
295 * Array of parameters determined by getfields.
297 function _civicrm_api3_mailing_event_reply_spec(&$params) {
298 $params['job_id']['api.required'] = 1;
299 $params['job_id']['title'] = 'Job ID';
300 $params['event_queue_id']['api.required'] = 1;
301 $params['event_queue_id']['title'] = 'Event Queue ID';
302 $params['hash']['api.required'] = 1;
303 $params['hash']['title'] = 'Hash';
304 $params['replyTo']['api.required'] = 0;
305 $params['replyTo']['title'] = 'Reply To';//doesn't really explain adequately
309 * Handle a forward event.
311 * @param array $params
315 function civicrm_api3_mailing_event_forward($params) {
316 $job = $params['job_id'];
317 $queue = $params['event_queue_id'];
318 $hash = $params['hash'];
319 $email = $params['email'];
320 $fromEmail = CRM_Utils_Array
::value('fromEmail', $params);
321 $params = CRM_Utils_Array
::value('params', $params);
323 $forward = CRM_Mailing_Event_BAO_Forward
::forward($job, $queue, $hash, $email, $fromEmail, $params);
326 return civicrm_api3_create_success($params);
329 return civicrm_api3_create_error('Queue event could not be found');
333 * Adjust Metadata for event_forward action.
335 * The metadata is used for setting defaults, documentation & validation.
337 * @param array $params
338 * Array of parameters determined by getfields.
340 function _civicrm_api3_mailing_event_forward_spec(&$params) {
341 $params['job_id']['api.required'] = 1;
342 $params['job_id']['title'] = 'Job ID';
343 $params['event_queue_id']['api.required'] = 1;
344 $params['event_queue_id']['title'] = 'Event Queue ID';
345 $params['hash']['api.required'] = 1;
346 $params['hash']['title'] = 'Hash';
347 $params['email']['api.required'] = 1;
348 $params['email']['title'] = 'Forwarded to Email';
352 * Handle a click event.
354 * @param array $params
358 function civicrm_api3_mailing_event_click($params) {
359 civicrm_api3_verify_mandatory($params,
360 'CRM_Mailing_Event_DAO_TrackableURLOpen',
361 array('event_queue_id', 'url_id'),
365 $url_id = $params['url_id'];
366 $queue = $params['event_queue_id'];
368 $url = CRM_Mailing_Event_BAO_TrackableURLOpen
::track($queue, $url_id);
371 $values['url'] = $url;
372 $values['is_error'] = 0;
374 return civicrm_api3_create_success($values);
378 * Handle an open event.
380 * @param array $params
384 function civicrm_api3_mailing_event_open($params) {
386 civicrm_api3_verify_mandatory($params,
387 'CRM_Mailing_Event_DAO_Opened',
388 array('event_queue_id'),
392 $queue = $params['event_queue_id'];
393 $success = CRM_Mailing_Event_BAO_Opened
::open($queue);
396 return civicrm_api3_create_error('mailing open event failed');
399 return civicrm_api3_create_success($params);
405 * @param array $params
406 * Array per getfields metadata.
409 * @throws \API_Exception
411 function civicrm_api3_mailing_preview($params) {
412 civicrm_api3_verify_mandatory($params,
413 'CRM_Mailing_DAO_Mailing',
419 if (!empty($params['from_email'])) {
420 $fromEmail = $params['from_email'];
423 $session = CRM_Core_Session
::singleton();
424 $mailing = new CRM_Mailing_BAO_Mailing();
425 $mailing->id
= $params['id'];
426 $mailing->find(TRUE);
428 CRM_Mailing_BAO_Mailing
::tokenReplace($mailing);
430 // get and format attachments
431 $attachments = CRM_Core_BAO_File
::getEntityFile('civicrm_mailing', $mailing->id
);
433 $returnProperties = $mailing->getReturnProperties();
434 $contactID = CRM_Utils_Array
::value('contact_id', $params);
436 $contactID = $session->get('userID');
438 $mailingParams = array('contact_id' => $contactID);
440 $details = CRM_Utils_Token
::getTokenDetails($mailingParams, $returnProperties, TRUE, TRUE, NULL, $mailing->getFlattenedTokens());
442 $mime = &$mailing->compose(NULL, NULL, NULL, $session->get('userID'), $fromEmail, $fromEmail,
443 TRUE, $details[0][$contactID], $attachments
446 return civicrm_api3_create_success(array(
447 'id' => $params['id'],
448 'contact_id' => $contactID,
449 'subject' => $mime->_headers
['Subject'],
450 'body_html' => $mime->getHTMLBody(),
451 'body_text' => $mime->getTXTBody(),
456 * Adjust metadata for send test function.
460 function _civicrm_api3_mailing_send_test_spec(&$spec) {
461 $spec['test_group']['title'] = 'Test Group ID';
462 $spec['test_email']['title'] = 'Test Email Address';
468 * @param array $params
471 * @throws \API_Exception
472 * @throws \CiviCRM_API3_Exception
474 function civicrm_api3_mailing_send_test($params) {
475 if (!array_key_exists('test_group', $params) && !array_key_exists('test_email', $params)) {
476 throw new API_Exception("Mandatory key(s) missing from params array: test_group and/or test_email field are required");
478 civicrm_api3_verify_mandatory($params,
479 'CRM_Mailing_DAO_MailingJob',
484 $testEmailParams = _civicrm_api3_generic_replace_base_params($params);
485 $testEmailParams['is_test'] = 1;
486 $job = civicrm_api3('MailingJob', 'create', $testEmailParams);
487 $testEmailParams['job_id'] = $job['id'];
488 $testEmailParams['emails'] = explode(',', $testEmailParams['test_email']);
489 if (!empty($params['test_email'])) {
490 $query = CRM_Utils_SQL_Select
::from('civicrm_email e')
491 ->select(array('e.id', 'e.contact_id', 'e.email'))
492 ->join('c', 'INNER JOIN civicrm_contact c ON e.contact_id = c.id')
493 ->where('e.email IN (@emails)', array('@emails' => $testEmailParams['emails']))
494 ->where('e.on_hold = 0')
495 ->where('c.is_opt_out = 0')
496 ->where('c.do_not_email = 0')
497 ->where('c.is_deceased = 0')
499 ->orderBy(array('e.is_bulkmail DESC', 'e.is_primary DESC'))
501 $dao = CRM_Core_DAO
::executeQuery($query);
502 $emailDetail = array();
503 // fetch contact_id and email id for all existing emails
504 while ($dao->fetch()) {
505 $emailDetail[$dao->email
] = array(
506 'contact_id' => $dao->contact_id
,
507 'email_id' => $dao->id
,
511 foreach ($testEmailParams['emails'] as $key => $email) {
512 $email = trim($email);
513 $contactId = $emailId = NULL;
514 if (array_key_exists($email, $emailDetail)) {
515 $emailId = $emailDetail[$email]['email_id'];
516 $contactId = $emailDetail[$email]['contact_id'];
519 //create new contact.
520 $contact = civicrm_api3('Contact', 'create',
522 'contact_type' => 'Individual',
524 'api.Email.get' => array('return' => 'id'),
527 $contactId = $contact['id'];
528 $emailId = $contact['values'][$contactId]['api.Email.get']['id'];
530 civicrm_api3('MailingEventQueue', 'create',
532 'job_id' => $job['id'],
533 'email_id' => $emailId,
534 'contact_id' => $contactId,
541 $config = CRM_Core_Config
::singleton();
542 $mailerJobSize = (property_exists($config, 'mailerJobSize')) ?
$config->mailerJobSize
: NULL;
543 while (!$isComplete) {
544 // Q: In CRM_Mailing_BAO_Mailing::processQueue(), the three runJobs*()
545 // functions are all called. Why does Mailing.send_test only call one?
546 // CRM_Mailing_BAO_MailingJob::runJobs_pre($mailerJobSize, NULL);
547 $isComplete = CRM_Mailing_BAO_MailingJob
::runJobs($testEmailParams);
548 // CRM_Mailing_BAO_MailingJob::runJobs_post(NULL);
551 //return delivered mail info
552 $mailDelivered = CRM_Mailing_Event_BAO_Delivered
::getRows($params['mailing_id'], $job['id'], TRUE, NULL, NULL, NULL, TRUE);
554 return civicrm_api3_create_success($mailDelivered);
558 * Adjust Metadata for send_mail action.
560 * The metadata is used for setting defaults, documentation & validation.
562 * @param array $params
563 * Array of parameters determined by getfields.
565 function _civicrm_api3_mailing_stats_spec(&$params) {
566 $params['date']['api.default'] = 'now';
567 $params['date']['title'] = 'Date';
571 * Function which needs to be explained.
573 * @param array $params
576 * @throws \API_Exception
578 function civicrm_api3_mailing_stats($params) {
579 civicrm_api3_verify_mandatory($params,
580 'CRM_Mailing_DAO_MailingJob',
585 if ($params['date'] == 'now') {
586 $params['date'] = date('YmdHis');
589 $params['date'] = CRM_Utils_Date
::processDate($params['date'] . ' ' . $params['date_time']);
592 $stats[$params['mailing_id']] = array();
593 if (empty($params['job_id'])) {
594 $params['job_id'] = NULL;
596 foreach (array('Delivered', 'Bounces', 'Unsubscribers', 'Unique Clicks', 'Opened') as $detail) {
599 $stats[$params['mailing_id']] +
= array(
600 $detail => CRM_Mailing_Event_BAO_Delivered
::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date']),
605 $stats[$params['mailing_id']] +
= array(
606 $detail => CRM_Mailing_Event_BAO_Bounce
::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date']),
610 case 'Unsubscribers':
611 $stats[$params['mailing_id']] +
= array(
612 $detail => CRM_Mailing_Event_BAO_Unsubscribe
::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, NULL, $params['date']),
616 case 'Unique Clicks':
617 $stats[$params['mailing_id']] +
= array(
618 $detail => CRM_Mailing_Event_BAO_TrackableURLOpen
::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, NULL, $params['date']),
623 $stats[$params['mailing_id']] +
= array(
624 $detail => CRM_Mailing_Event_BAO_Opened
::getTotalCount($params['mailing_id'], $params['job_id'], FALSE, $params['date']),
629 return civicrm_api3_create_success($stats);
633 * Fix the reset dates on the email record based on when a mail was last delivered.
635 * We only consider mailings that were completed and finished in the last 3 to 7 days
636 * Both the min and max days can be set via the params
638 * @param array $params
642 function civicrm_api3_mailing_update_email_resetdate($params) {
643 CRM_Mailing_Event_BAO_Delivered
::updateEmailResetDate(
644 CRM_Utils_Array
::value('minDays', $params, 3),
645 CRM_Utils_Array
::value('maxDays', $params, 3)
647 return civicrm_api3_create_success();