Child pages
  • WHM API 1 Functions - emailtrack_stats
Skip to end of metadata
Go to start of metadata

Description

This function retrieves email tracking statistics.

Important:

In cPanel & WHM version 76 and later, when you disable the MailSend role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/emailtrack_stats?api.version=1
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/emailtrack_stats?api.version=1
 Command Line
whmapi1 emailtrack_stats


Notes:

  • You must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 Output (JSON)
{
  "data": {
    "records": [
      {
        "TOTALSIZE": "26357",
        "SUCCESSCOUNT": "17",
        "SENDCOUNT": "18",
        "DEFERCOUNT": "0",
        "FAILCOUNT": "1",
        "INPROGRESSCOUNT": "0",
        "DEFERFAILCOUNT": "1"
      }
    ]
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "overflowed": 0,
    "result": 1,
    "command": "emailtrack_stats"
  }
}
 Output (XML)
<result>
    <data>
        <records>
            <TOTALSIZE>26357</TOTALSIZE>
            <SUCCESSCOUNT>17</SUCCESSCOUNT>
            <SENDCOUNT>18</SENDCOUNT>
            <DEFERCOUNT>0</DEFERCOUNT>
            <FAILCOUNT>1</FAILCOUNT>
            <INPROGRESSCOUNT>0</INPROGRESSCOUNT>
            <DEFERFAILCOUNT>1</DEFERFAILCOUNT>
        </records>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <overflowed>0</overflowed>
        <result>1</result>
        <command>emailtrack_stats</command>
    </metadata>
</result>


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
userstring

The cPanel username to query.

If you do not specify a value, the function retrieves statistics for all of the server's accounts.

A valid cPanel username that exists on the server.

username
starttimeinteger

The start time of the search window.

This parameter defaults to 0.

A valid date in Unix time format.1371552781
endtimeinteger

The end time of the search window.

This parameter defaults to the current time.

A valid date in Unix time format.1471552781
deliverytypestring

The type of delivery to query.

If you do not specify a value, this function returns all types.

  • remote
  • remote-or-faildefer
  • local
remote
nosuccessBoolean

Whether to return the SUCCESSCOUNT parameter.

This parameter defaults to 0.

  • 1 — Do not return.
  • 0 — Return.
0
nosizeBoolean

Whether to return the TOTALSIZE parameter.

This parameter defaults to 0.

  • 1 — Do not return.
  • 0 — Return.
0

Returns

ReturnTypeDescriptionPossible valuesExample
recordsarray of hashesAn array of hashes of the message information.Each hash includes the DEFERMAILCOUNT, TOTALSIZE, SUCCESSCOUNT, SENDCOUNT, DEFERCOUNT, FAILCOUNT, and INPROGRESSCOUNT returns. 

DEFERMAILCOUNT

integer

The number of messages that the system deferred and failed to deliver.

The function returns this value in the records hash.

A positive integer.0

TOTALSIZE

integer

The total size of messages that the server sent.

The function returns this value in the records hash.

A positive integer that measures the total size in bytes.27444

SUCCESSCOUNT

integer

The number of successful deliveries.

The function returns this value in the records hash.

Note:

If a message has three recipients, it can have a total of three successful deliveries.

A positive integer.14

SENDCOUNT

integer

The number of sent messages.

The function returns this value in the records hash.

A positive integer.14

DEFERCOUNT

integer

The number of deferral events.

The function returns this value in the records hash.

A positive integer.0

FAILCOUNT

integer

The number of delivery failures.

The function returns this value in the records hash.

Note:

If a message has three recipients, it can have a total of three failed deliveries.

A positive integer.0

INPROGRESSCOUNT

integer

The number of messages currently in progress.

The function returns this value in the records hash.

A positive integer.1