Page tree
Skip to end of metadata
Go to start of metadata

 

Description

This function retrieves email delivery records.

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. 
  • We introduced this functionality in cPanel & WHM version 11.52.0.8.

 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