WHM API: emailtrack_search returns empty records – CPanel

Daniel, the empty records array was driving me crazy as well. Your findings helped me dig deeper into cPanel’s badly documented API. To help others looking for similar answers, I detailed the process in a blog post – Email delivery reports using WHM API and PHP

Edit: Here’s a piece of my code that returns results from WHM’s JSON API, using emailtrack_search:

function fetchRecordsByHour($sender, $startTime, $endTime) {
  //Set up variables
  $user = USER;
  $token = TOKEN;
  $hostname = HOSTNAME;

  //Set up query - https://documentation.cpanel.net/display/DD/WHM+API+1+Functions+-+emailtrack_search
  $query = $hostname.'/json-api/emailtrack_search?api.version=1'.
            '&api.filter.enable=1'. //Enable filter (https://documentation.cpanel.net/display/DD/WHM+API+1+-+Filter+Output)
            '&api.filter.a.field=sender&api.filter.a.arg0='.$sender.'&api.filter.a.type=eq'. //Filter records with $sender
            '&api.filter.b.field=sendunixtime&api.filter.b.arg0='.$startTime.'&api.filter.b.type=gt'. //Filter records greater than $startTime
            '&api.filter.c.field=sendunixtime&api.filter.c.arg0='.$endTime.'&api.filter.c.type=lt'. //Filter records less than $endTime
            '&api.sort.enable=1'. //Enable sorting (https://documentation.cpanel.net/display/DD/WHM+API+1+-+Sort+Output)
            '&api.sort.a.field=sendunixtime&api.sort.a.method=numeric&api.sort.a.reverse=0'. //Sort by sent time, not in reverse (By default, the API sorts in reverse order)
            '&success=1'. //Fetch success emails
            '&defer=1'. //Fetch defered emails
            '&failure=1'. //Fetch failed emails
            '&inprogress=1'. //Fetch in progress emails
            '&deliverytype=all'. //Fetch remote and local emails
            '&max_results_by_type=999'; // Fetch a large number of records per batch (Since WHM limits the total at 250 records, anything above 250 is fine)

  //Initialize CURL
  $curl = curl_init();
  curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
  curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($curl, CURLOPT_URL, $query);

  //Set authentication parameters
  $header[0] = "Authorization: whm $user:$token";
  curl_setopt($curl, CURLOPT_HTTPHEADER, $header);

  $result = curl_exec($curl);

  //Check for CURL error
  $http_status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
  if ($http_status != 200) {
    echo "Error: ".$http_status." returned";
  }

  curl_close($curl);

  //Return only the records, stripping away all the metadata
  return json_decode($result)->data->records;
}