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

Description

This function retrieves email delivery records.

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_search?api.version=1
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/emailtrack_search?api.version=1
 Command Line
whmapi1 emailtrack_search


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":[
         {
            "transport":null,
            "senderauth":"localuser",
            "recipient":"yoegt@ymail.com",
            "msgid":"1RuV0Z-0005NR-BN",
            "ip":null,
            "senderip":"127.0.0.1",
            "actionunixtime":"1328559471",
            "domain":"example.com",
            "size":"1653",
            "type":"failure",
            "actiontime":"2012-02-06 14:17:51",
            "transport_is_remote":"0",
            "message":"Domain example.com has exceeded the max defers and failures per hour (5/5 (100%)) allowed. Message discarded.",
            "host":null,
            "sendunixtime":"1328559471",
            "user":"cpanel1",
            "senderhost":"localhost",
            "router":"enforce_mail_permissions",
            "deliverydomain":"",
            "deliveryuser":"",
            "spamscore":null,
            "sender":"cpanel1@publicdocs.cpanel.net",
            "deliveredto":null
         }
      ]
   },
   "metadata":{
      "result":1,
      "reason":"OK",
      "version":1,
      "command":"emailtrack_search"
   }
}
 Output (XML)
<result>
   <data>
      <records>
         <transport/>
         <senderauth>localuser</senderauth>
         <recipient>yoegt@ymail.com</recipient>
         <msgid>1RuV0Z-0005NR-BN</msgid>
         <ip/>
         <senderip>127.0.0.1</senderip>
         <actionunixtime>1328559471</actionunixtime>
         <domain>example.com</domain>
         <size>1653</size>
         <type>failure</type>
         <actiontime>2012-02-06 14:17:51</actiontime>
         <transport_is_remote>0</transport_is_remote>
         <message>Domain
 example.com has exceeded the max defers and failures per hour (5/5 
(100%)) allowed. Message discarded.</message>
         <host/>
         <sendunixtime>1328559471</sendunixtime>
         <user>cpanel1</user>
         <senderhost>localhost</senderhost>
         <router>enforce_mail_permissions</router>
         <deliverydomain/>
         <deliveryuser/>
         <spamscore/>
         <sender>cpanel1@publicdocs.cpanel.net</sender>
         <deliveredto/>
      </records>
   </data>
   <metadata>
      <result>1</result>
      <reason>OK</reason>
      <version>1</version>
      <command>emailtrack_search</command>
   </metadata>
</result>


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
nosizeBoolean

Whether to return successful delivery attempts.

This parameter defaults to 0.

  • 1Return successful delivery attempts.
  • 0 — Do not return successful delivery attempts.
0
deferBoolean

Whether to return delivery deferral events.

This parameter defaults to 0.

  • 1Return delivery deferral events.
  • 0 — Do not return delivery deferral events.
0
failureBoolean

Whether to return delivery failure events.

This parameter defaults to 0.

  • 1Return delivery failure events.
  • 0 — Do not return delivery failure events.
0
inprogressBoolean

Whether to return delivery attempts in progress.

This parameter defaults to 0.

  • 1Return delivery attempts in progress.
  • 0 — Do not return delivery attempts in progress.
0
deliverytypestring

The type of delivery records to retrieve.

This parameter defaults to all.

  • all — Retrieve all delivery records.
  • remote — Retrieve remote delivery records.
  • local — Retrieve local delivery records.
all
max_results_by_typeinteger

The number of results to return for each type.

This parameter defaults to 0.

A valid positive integer.

Note:

If you set this parameter to 0, the function returns unlimited results.

3

Returns

ReturnTypeDescriptionPossible valuesExample
recordsarray of hashesAn array of hashes of the delivery record.Each hash includes the transport, senderauth, recipient, msdig, ip, senderip, actionunixtime, domain, size, type, actiontime, transport_is_remote, message, host, sendunixtime, user, senderhost, router, deliverydomain, deliveryuser, spamscore, sender, and deliverdto returns. 

transport

string

The mail transfer agent (MTA).

The function returns this value in the records array.

A valid string.null

senderauth

string

The user authentication.

The function returns this value in the records array.

A valid string.localuser

recipient

string

The recipient's mail address.

The function returns this value in the records array.

A valid email address.yoegt@ymail.com

msdig

string

The message ID.

The function returns this value in the records array.

A valid string.1RuV0Z-0005NR-BN

ip

string

The recipient's IP address.

The function returns this value in the records array.

A valid IP address.null

senderip

string

The sender's IP address.

The function returns this value in the records array.

A valid IP address.127.0.0.1

actionunixtime

string

When the delivery attempt happened.

The function returns this value in the records array.

A valid date in Unix time format.1328559471

domain

string

The sender's domain.

The function returns this value in the records array.

A valid domain name.example.com

size

string

The message's size.

The function returns this value in the records array.

A valid positive integer that measures the message size in bytes.1653

type

string

The delivery status.

The function returns this value in the records array.

  • success
  • defer
  • failure
  • inprogress
success

actiontime

string

When the delivery attempt happened.

The function returns this value in the records array.

The date in YYYY-MM-DD HH-mm-SS human-readable format, where:

  • YYYY represents the year.
  • MM represents the month.
  • DD represents the date.
  • HH represents the hour.
  • mm represents the minute.
  • SS represents the second.
2012-02-06 14:17:51

transport_is_remote

Boolean

Whether the mail transfer agent (MTA) is remote.

The function returns this value in the records array.

  • 1 — Remote.
  • 0Not remote.
0

message

string

The action taken.

The function returns this value in the records array.

A valid string.Domain example.com has exceeded the max defers and failures per hour (5/5 (100%)) allowed. Message discarded.

host

string

The hostname that received the message.

The function returns this value in the records array.

A valid hostname.null

sendunixtime

integer

When the message was sent.

The function returns this value in the records array.

A valid date in Unix time format.1328559471

user

string

The sender's username.

The function returns this value in the records array.

A valid username.cpanel1

senderhost

string

The sender's hostname.

The function returns this value in the records array.

A valid hostname.localhost

router

string

The mail server's internal router name.

The function returns this value in the records array.

A valid string.enforce_mail_permissions

deliverydomain

string

The recipient's domain.

The function returns this value in the records array.

A valid domain name.null

deliveryuser

string

The recipient's username.

The function returns this value in the records array.

A valid username.null

spamscore

string

The message's spam score.

The function returns this value in the records array.

A numeric value.

Note:

If the spam prevention engine uses a result range from 0 to 1, the system multiplies the result by 10.

5

sender

string

The sender's full email address.

The function returns this value in the records array.

A valid email address.user@example.com

deliveredto

string

The delivery attempt's final end point.

The function returns this value in the records array.

  • An absolute file path to a script that routes email.

  • A valid email address. 

    Note:

    If the message went to a mailing list, the address will be the mailing list member's address.

null