3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
13 * This api exposes CiviCRM contact and mailing.
15 * @package CiviCRM_APIv3
19 * Get all the mailings and details that a contact was involved with.
21 * @param array $params
22 * Input parameters - see _spec for details (returned by getfields)
27 function civicrm_api3_mailing_contact_get($params) {
28 return civicrm_api3_create_success(_civicrm_api3_mailing_contact_getresults($params, FALSE));
32 * This is a wrapper for the functions that return the results from the 'quasi-entity' mailing contact.
34 * @param array $params
39 function _civicrm_api3_mailing_contact_getresults($params, $count) {
40 if (empty($params['type'])) {
41 //ie. because the api is an anomaly & passing in id is not valid
42 throw new Exception('This api call does not accept api as a parameter');
44 $options = _civicrm_api3_get_options_from_params($params, TRUE, 'contribution', 'get');
45 $fnName = '_civicrm_api3_mailing_contact_get_' . strtolower($params['type']);
46 if (!function_exists($fnName)) {
47 throw new API_Exception('Invalid mailing type: ' . $params['type']);
50 $params['contact_id'],
59 * Adjust Metadata for Get action.
61 * @param array $params
62 * Array of parameters determined by getfields.
64 function _civicrm_api3_mailing_contact_get_spec(&$params) {
65 $params['contact_id'] = [
67 'title' => 'Contact ID',
68 'type' => CRM_Utils_Type
::T_INT
,
72 'api.default' => 'Delivered',
73 // doesn't really explain the field - but not sure I understand it to explain it better
75 'type' => CRM_Utils_Type
::T_STRING
,
77 'Delivered' => 'Delivered',
78 'Bounced' => 'Bounced',
84 * Helper function for mailing contact queries.
86 * @param int $contactID
89 * @param array|null $selectFields
90 * @param string|null $fromClause
91 * @param string|null $whereClause
92 * @param string|null $sort
93 * @param bool $getCount
97 function _civicrm_api3_mailing_contact_query(
111 FROM civicrm_mailing m
112 INNER JOIN civicrm_contact c ON m.created_id = c.id
113 INNER JOIN civicrm_mailing_job j ON j.mailing_id = m.id
114 INNER JOIN civicrm_mailing_event_queue meq ON meq.job_id = j.id
117 AND meq.contact_id = %1
123 1 => [$contactID, 'Integer'],
125 $dao = CRM_Core_DAO
::executeQuery($sql, $qParams);
131 'm.id' => 'mailing_id',
132 'm.subject' => 'subject',
133 'c.id' => 'creator_id',
134 'c.sort_name' => 'creator_name',
138 $fields = array_merge($selectFields, $defaultFields);
141 $fields = $defaultFields;
145 foreach ($fields as $n => $l) {
146 $select[] = "$n as $l";
148 $select = implode(', ', $select);
150 $orderBy = 'ORDER BY MIN(j.start_date) DESC';
152 $orderBy = "ORDER BY $sort";
155 $groupBy = CRM_Contact_BAO_Query
::getGroupByFromSelectColumns(array_keys($fields), "m.id");
159 FROM civicrm_mailing m
160 INNER JOIN civicrm_contact c ON m.created_id = c.id
161 INNER JOIN civicrm_mailing_job j ON j.mailing_id = m.id
162 INNER JOIN civicrm_mailing_event_queue meq ON meq.job_id = j.id
165 AND meq.contact_id = %1
178 1 => [$contactID, 'Integer'],
179 2 => [$offset, 'Integer'],
180 3 => [$limit, 'Integer'],
182 $dao = CRM_Core_DAO
::executeQuery($sql, $qParams);
185 while ($dao->fetch()) {
186 foreach ($fields as $n => $l) {
187 $results[$dao->mailing_id
][$l] = $dao->$l;
196 * Get delivered mailing contacts.
198 * @param int $contactID
201 * @param string|null $sort
202 * @param bool $getCount
206 function _civicrm_api3_mailing_contact_get_delivered(
213 $selectFields = ['med.time_stamp' => 'start_date'];
216 INNER JOIN civicrm_mailing_event_delivered med ON med.event_queue_id = meq.id
217 LEFT JOIN civicrm_mailing_event_bounce meb ON meb.event_queue_id = meq.id
224 return _civicrm_api3_mailing_contact_query(
237 * Get bounced mailing contact records.
239 * @param int $contactID
242 * @param string|null $sort
243 * @param bool $getCount
247 function _civicrm_api3_mailing_contact_get_bounced(
255 INNER JOIN civicrm_mailing_event_bounce meb ON meb.event_queue_id = meq.id
258 return _civicrm_api3_mailing_contact_query(
271 * Get count of all the mailings that a contact was involved with.
273 * @param array $params
274 * Input parameters per getfields
279 function civicrm_api3_mailing_contact_getcount($params) {
280 return _civicrm_api3_mailing_contact_getresults($params, TRUE);