Child pages
  • UAPI Functions - Email::trace_delivery
Skip to end of metadata
Go to start of metadata

Description

This function traces the email delivery route to an email account.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Email/trace_delivery?recipient=username@example.com


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Trace the delivery of an email message to a recipient.
$variable = $cpanel->uapi(
    'Email', 'trace_delivery',
    array(
        'recipient'    => 'username@example.com'
         )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Trace the delivery of an email message to a recipient.
my $variable = $cpliveapi->uapi(
    'Email', 'trace_delivery',
    {
        'recipient'     => 'username@example.com'
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

 Command Line
uapi --user=username Email trace_delivery recipient=username@example.com


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
    "apiversion":3,
    "module":"Email",
    "func":"trace_delivery",
    "result":{
        "messages":null,
        "metadata":{

        },
        "warnings":null,
        "data":{
            "type":"routed",
            "address":"username@example.com",
            "destinations":[
                {
                    "aliasfile":"/etc/valiases/example.com",
                    "type":"routed",
                    "destinations":[
                        {
                            "mailbox":"username@example.com",
                            "type":"local_delivery"
                        }
                    ],
                    "address":"username@example.com"
                }
            ]
        },
        "status":1,
        "errors":null
    }
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
recipient string

Required

The email address to which to trace a message delivery path.

A valid email address.

username@example.com 

Returns

ReturnTypeDescriptionPossible valuesExample

address

stringThe email address of an email message recipient.A valid email address.username@example.com 

type

string

A type of trace node. The system returns this value to indicate the end of routing.

For more information, see the type return value section below.

  • bounce — The system rejected the email's delivery.
  • command — The system will run a command when it receives an email.
  • defer — The system deferred the email.
  • discard — The system discarded the email.
  • error — The system encountered an error.
  • local_delivery — The system sent the email to a local mailbox.
  • remote_delivery — The system sent the email via Simple Mail Transfer Protocol (SMTP).
  • routed — The system routed the email elsewhere.
local_delivery

The type return value

This value will modify the function's output hash:

routed

 Click here to expand...
ReturnTypeDescriptionPossible valuesExample
destinationshashAn array of hashes for the address return value. Each hash indicates the status of email delivery to the email address.

Each hash contains the type return. It also contains any other valid type return values.


bounce

 Click to view...
ReturnTypeDescriptionPossible valuesExample

message

string

A message that the system sends when it rejects the delivery of an email.

A valid string.The system rejected the message.

command

 Click here to expand...
ReturnTypeDescriptionPossible valuesExample

command

string

A command that the system runs when it receives the email.

A valid command.
 Click to view...

/usr/local/cpanel/bin/autorespond user@example.com /home/cpmailuser/.autorespond

defer

 Click here to expand...
ReturnTypeDescriptionPossible valuesExample

message

string

A message that the system sends when it defers the email.

A valid string.The system deferred the message.

discard

 Click here to expand...
ReturnTypeDescriptionPossible valuesExample
aliasfilestringThe file path on the system where Exim searched for the address return value's aliases.

A valid file path.

Note:

The function only returns this value if an alias exists for the address value.

/etc/valiases/example.com

error

 Click here to expand...
ReturnTypeDescriptionPossible valuesExample

message

string

An error message from the system.

A valid string.
 Click to view...

The mail server could not deliver mail to user@example2.com. The account or domain may not exist, they may be blacklisted, or missing the proper dns entries.



result

string

An error message.

A valid string.

DNS lookup of example2.com (MX) gave HOST_NOT_FOUND

local_delivery

 Click here to expand...
ReturnTypeDescriptionPossible valuesExample

mailbox

string

The mailbox where the system sent the email.

A valid email address.user@example.com

remote_delivery

 Click here to expand...
ReturnTypeDescriptionPossible valuesExample

mx 

hash

An array of mail exchanger (MX) hash references.

For more information, read Wikipedia's MX record article.

Each hash includes the hostnameip, and priority returns.

hostname

string

The server hostname.

This function returns this value in the mx hash.

A valid hostname.example.com

ip

string

The server IP address.

This function returns this value in the mx hash.

A valid IP address.10.0.0.1

priority

integer

The MX record's priority number. The lower the value, the higher its priority.

This function returns this value in the mx hash.

A positive integer.10