API returns forward information different

gunsuka

Member
Jan 18, 2015
10
0
1
cPanel Access Level
Root Administrator
I always assumed if we did not change the API version, the data returned would remain the same.

Seems that is not true :-(

For years I have been calling the listforwards command.

I was using two pieces of data from that command:

dest - An email address on the cPanel account, in plaintext.
forward - The address to which the system forwards mail, or the method that the system uses to handle mail, in plaintext.

So in the forward field would show an address that forwards to the destination.

I query a lot of different cPanel servers. Seems some newer builds it has switched and dest is forward.

I was going through the cPanel release notes and found in build 59.9999.73 this comment:

Fixed case CPANEL-8000: Fix UI order of email forwarder and destination.

So am I correct to assume that whatever that change was has impacted the API calls. Any call made to a server > 59.9999.73 the dest & forward addresses are reversed?
 

cPanelKenneth

cPanel Development
Staff member
Apr 7, 2006
4,607
80
458
cPanel Access Level
Root Administrator
Hi,

As the change log noted, the problem was with the UI. The API was fine.
 

gunsuka

Member
Jan 18, 2015
10
0
1
cPanel Access Level
Root Administrator
I went looking for the change log to see if something in the change log may explain what I see happening on the servers.

I can confirm that for the two fields have been switched around in newer versions of the API. I am currently modifying our system so when we query a server we first ask for the cPanel version. Then from there we will be able to hack our code to normalize what the API is returning.
 

gunsuka

Member
Jan 18, 2015
10
0
1
cPanel Access Level
Root Administrator
Here is a snippet of the results I get back using API 2 function Email::listforwards

cPanel version - 11.56.0.36
Code:
[0] => stdClass Object
(
  [forward] => [email protected]
  [uri_forward] => orders%40example.com
  [html_dest] => [email protected]
  [dest] => [email protected]
  [uri_dest] => accounting%40example.com
  [html_forward] => [email protected]
)
The message arrives to [dest] address ([email protected]) and is delivered to [forward] address ([email protected]). This MATCHES the API documentation as of 2016-11-07.


cPanel version - 11.60.0.15
Code:
[0] => stdClass Object
(
  [html_dest] => [email protected]
  [html_forward] => [email protected]
  [forward] => [email protected]
  [uri_forward] => accounting%40example.com
  [uri_dest] => orders%40example.com
  [dest] => [email protected]
)
The message arrives to [forward] address ([email protected]) and is delivered to [dest] address ([email protected]). This is the exact opposite of the previous example and the opposite of the API documentation. I don't know what version of cPanel it changed in, I only mention the release notes because it sorta matches the time frame.

The email makes it to the correct destination in both cases but the labels have changed, so people who are using the API and relying on [dest] and [forward] as the logic got a big suprise when it becomes reversed and their code breaks.

Fortunately for us we caught it before a lot of cPanel servers have upgraded. Most of our customers are still running 58.xx and we believe the bug came in 59.xx somewhere.
 
Last edited by a moderator:

cPanelMichael

Administrator
Staff member
Apr 11, 2011
47,884
2,254
463
Hello @gunsuka,

The API behavior when listing email forwarders changed in cPanel version 60 due to the following case:

Fixed case CPANEL-6434: Email::list_forwarders returns documented values.

For example, let's say the following email account exists under an account:

[email protected]

We then setup a forwarder to forward emails from [email protected] to [email protected]. This results in the following output on cPanel version 58 for cPanel API 2:

Code:
# cpapi2 --user=cptest01 Email listforwards domain=cptest01.tld
---
cpanelresult:
  apiversion: 2
  data:
    -
      dest: [email protected]
      forward: [email protected]
      html_dest: [email protected]
      html_forward: [email protected]
      uri_dest: test1%40cptest01.tld
      uri_forward: test2%40cptest01.tld
  event:
    result: 1
  func: listforwards
  module: Email
Here's the output in cPanel 58 using UAPI:

Code:
# uapi --user=cptest01 Email list_forwarders domain=cptest01.tld
---
apiversion: 3
func: list_forwarders
module: Email
result:
  data:
    -
      dest: [email protected]
      forward: [email protected]
      html_dest: [email protected]
      html_forward: [email protected]
      uri_dest: test1%40cptest01.tld
      uri_forward: test2%40cptest01.tld
  errors: ~
  messages: ~
  metadata:
    transformed: 1
  status: 1
This matches the documentation at:

cPanel API 2 Functions - Email::listforwards - Software Development Kit - cPanel Documentation

dest
string The email address, in plaintext. An email address on the cPanel account, in plaintext.
forward
string The address to which the system forwards mail, or the method that the system uses to handle mail, in plaintext.
However, it did not match the documentation at:

https://documentation.cpanel.net/display/SDK/UAPI+Functions+-+Email::list_forwarders

dest
string The forwarded mail's destination. The location to which the system sends forwarded mail.
forward
string The forwarded address. An email address on the cPanel account.
Thus, internal case CPANEL-6434 was opened to ensure the list forwarders API functionality matched what was documented on the UAPI documentation. This changed the behavior in cPanel version 60 to the following:

Code:
# uapi --user=cptest01 Email list_forwarders domain=cptest01.tld
---
apiversion: 3
func: list_forwarders
module: Email
result:
  data:
  -
  dest: [email protected]
  forward: [email protected]
  html_dest: [email protected]
  html_forward: [email protected]
  uri_dest: test2%40cptest01.tld
  uri_forward: test1%40cptest01.tld
  errors: ~
  messages: ~
  metadata:
  transformed: 1
  status: 1
Code:
# cpapi2 --user=cptest01 Email listforwards domain=cptest01.tld
---
cpanelresult:
  apiversion: 2
  data:
    -
      dest: [email protected]
      forward: [email protected]
      html_dest: [email protected]
      html_forward: [email protected]
      uri_dest: test2%40cptest01.tld
      uri_forward: test1%40cptest01.tld
  event:
    result: 1
  func: listforwards
  module: Email
I've opened a case with our documentation team to ensure the following document is updated to reflect this new behavior:

cPanel API 2 Functions - Email::listforwards - Software Development Kit - cPanel Documentation

I'll update this thread once the changes are published.

Thank you.
 

cPanelMichael

Administrator
Staff member
Apr 11, 2011
47,884
2,254
463
Hello @gunsuka,

We now have a new internal case open, CPANEL-9743, to evaluate the changes referenced in my previous response stemming from CPANEL-6434. There's no decision to report at this time, but I wanted to keep you in the loop as I understand you spent some time making modifications to your custom applications to account for this change. I'll update this thread with more information as it becomes available.

Thank you.
 

cPanelMichael

Administrator
Staff member
Apr 11, 2011
47,884
2,254
463
Hello,

To update, the changes made in cPanel version 60 referenced in my earlier response are reverted as of cPanel version 60.0.22. The behavior now matches cPanel version 58 and earlier.

Thank you.