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

Description

This function retrieves email tracking statistics for each user.

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_user_stats?api.version=1
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/emailtrack_user_stats?api.version=1
 Command Line
whmapi1 emailtrack_user_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": [
      {
        "DEFERFAILCOUNT": "0",
        "REACHED_MAXEMAILS": 0,
        "TOTALSIZE": "108125",
        "SUCCESSCOUNT": "68",
        "SENDCOUNT": "68",
        "DEFERCOUNT": "0",
        "FAILCOUNT": "0",
        "REACHED_MAXDEFERFAIL": 0,
        "DOMAIN": "",
        "USER": "root",
        "PRIMARY_DOMAIN": "",
        "OWNER": "root"
      },
      {
        "DEFERFAILCOUNT": "0",
        "REACHED_MAXEMAILS": 0,
        "TOTALSIZE": "27444",
        "SUCCESSCOUNT": "14",
        "SENDCOUNT": "14",
        "DEFERCOUNT": "0",
        "FAILCOUNT": "0",
        "REACHED_MAXDEFERFAIL": 0,
        "DOMAIN": "example.com",
        "USER": "example",
        "PRIMARY_DOMAIN": "example.com",
        "OWNER": "root"
      }
    ]
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "overflowed": 0,
    "result": 1,
    "command": "emailtrack_user_stats"
  }
}
 Output (XML)
<result>
    <data>
        <records>
            <DEFERFAILCOUNT>0</DEFERFAILCOUNT>
            <REACHED_MAXEMAILS>0</REACHED_MAXEMAILS>
            <TOTALSIZE>108125</TOTALSIZE>
            <SUCCESSCOUNT>68</SUCCESSCOUNT>
            <SENDCOUNT>68</SENDCOUNT>
            <DEFERCOUNT>0</DEFERCOUNT>
            <FAILCOUNT>0</FAILCOUNT>
            <REACHED_MAXDEFERFAIL>0</REACHED_MAXDEFERFAIL>
            <DOMAIN/>
            <USER>root</USER>
            <PRIMARY_DOMAIN/>
            <OWNER>root</OWNER>
        </records>
        <records>
            <DEFERFAILCOUNT>0</DEFERFAILCOUNT>
            <REACHED_MAXEMAILS>0</REACHED_MAXEMAILS>
            <TOTALSIZE>27444</TOTALSIZE>
            <SUCCESSCOUNT>14</SUCCESSCOUNT>
            <SENDCOUNT>14</SENDCOUNT>
            <DEFERCOUNT>0</DEFERCOUNT>
            <FAILCOUNT>0</FAILCOUNT>
            <REACHED_MAXDEFERFAIL>0</REACHED_MAXDEFERFAIL>
            <DOMAIN>example.com</DOMAIN>
            <USER>example</USER>
            <PRIMARY_DOMAIN>example.com</PRIMARY_DOMAIN>
            <OWNER>root</OWNER>
        </records>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <overflowed>0</overflowed>
        <result>1</result>
        <command>emailtrack_user_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
recordsstring

The email address to query.

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

A valid email address.

user@example.com
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

Returns

ReturnTypeDescriptionPossible valuesExample
recordsarray of hashesAn array of hashes of the message information.Each hash includes the DEFERMAILCOUNT, REACHED_MAXEMAILS, TOTALSIZE, SUCCESSCOUNT, SENDCOUNT, DEFERCOUNT, FAILCOUNT, REACHED_MAXDEFERFAIL, DOMAIN, USER, PRIMARY_DOMAIN, and OWNER returns. 

DEFERMAILCOUNT

integer

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

The function returns this value in the records array.

A positive integer.0

REACHED_MAXEMAILS

Boolean

Whether the mailbox has reached the maximum number of messages allowed per hour.

The function returns this value in the records array.

  • 1 — Reached.
  • 0 — Has not reached.
1

TOTALSIZE

integer

The total size of messages sent by the server.

The function returns this value in the records array.

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 array.

Note:

If you assign a message three recipients, the system can successfully deliver the message three times.

A positive integer.14

SENDCOUNT

integer

The number of sent messages.

The function returns this value in the records array.

A positive integer.14

DEFERCOUNT

integer

The number of deferral events.

The function returns this value in the records array.

A positive integer.0

FAILCOUNT

integer

The number of delivery failures.

The function returns this value in the records array.

Note:

If you assign a message three recipients, the system can fail to deliver the message three times.

A positive integer.0

REACHED_MAXDEFERFAIL

Boolean

Whether the mailbox reached the maximum number of failed deferred messages.

The function returns this value in the records array.

  • 1 — Reached.
  • 0 — Has not reached.
1

DOMAIN

string

The mailbox's domain.

The function returns this value in the records array.

A valid domain name.example.com

USER

string

The mailbox's owner.

The function returns this value in the records array.

A valid username.example

PRIMARY_DOMAIN

string

The mailbox account's primary domain.

The function returns this value in the records array.

A valid domain name.example.com

OWNER

string

The mailbox's account owner.

The function returns this value in the records array.

A valid username.root