We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

Child pages
  • UAPI Functions - Session::create_webmail_session_for_mail_user
Skip to end of metadata
Go to start of metadata

Description

This function creates a temporary session for a cPanel user to connect to Webmail on a linked mail node server.

Note:

The cPanel user must own the Webmail account.

Examples


 cPanel Session URL
https://hostname.example.com:2083/cpsess##########/execute/Session/create_webmail_session_for_mail_user?login=username&domain=example.com&locale=en&remote_address=192.168.0.1


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.
 
// Create a temporary session to connect to a Mail Node profile server.
$variable = $cpanel->uapi(
    'Session', 'create_webmail_session_for_mail_user',
    array(
		'login'			 => 'username',
		'domain'		 => 'example.com',
        'locale'    	 => 'en',
		'remote_address' => '192.168.0.1',
         )
);


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.
 
# Create a temporary session to connect to a Mail Node profile server.
my $variable = $cpliveapi->uapi(
    'Session', 'create_webmail_session_for_mail_user',
    {
		'login'			 => 'username',
		'domain'		 => 'example.com',
        'locale'     	 => 'en',
		'remote_address' => '192.168.0.1',
    }
);


Note:

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

 Command Line

Warning:

You  must  enter the  remote_address  parameter if you run this function from the command line.

uapi --user=username Session create_webmail_session_for_mail_user login=username domain=example.com locale=en remote_address=192.168.0.1
 Output (JSON)
{
  "data": {
      "session":"username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137",
      "token":"/cpsess2462418786",
      "hostname":192.168.0.1
  },
  "messages": null,
  "errors": null,
  "status": 1,
  "metadata": {
    "transformed": 1
  }
}


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
loginstring

Required 

The Webmail user's username.

A valid username for the domain that you specify.username
domainstring

Required 

The domain for the email account.

A valid domain for the username that you specify.example.com
localestring

The locale that the new session will use.

This parameter defaults to the server's locale.

A valid locale.

Note:

You must only enter lowercase characters.

en
remote_addressstring

The Webmail user's client IP address.

Note:

If you run this function from the command line, this parameter is required .

This parameter defaults to the API caller's IP address.

A valid IP address.192.168.0.1


Returns

ReturnTypeDescriptionPossible valuesExample
tokenstring

A new security token.

A valid security token.

/cpsess2462418786

sessionstring

The session value to submit via POST to begin using the new session.

A valid string.
username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137
hostnamestring

The hostname of the linked mail node.

  • A valid hostname.
  • null

    Note:

    The function returns a null value when Webmail server is not remote.
hostname.example.com

Submit via POST

Send an HTTP POST to https://$URL_AUTHTY:2096$token/login with a message body of session=$session where:

  • $URL_AUTHTY represents the value from the hostname return.
    • If the hostname return value is null, enter the hostname of the server that answered the API function.
  • $token represents the value from the token return.
  • $session represents the value of the session return.

For example, an HTTP POST may resemble the following:

https://hostname.example.com:2096/cpsess2462418786/login

With a message body of:

session=username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137