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_check_password
Skip to end of metadata
Go to start of metadata

Description

This function creates a temporary session with a password for the calling cPanel user to connect to Webmail.

Note:

  • The cPanel user must own the Webmail account.
  • This function works like the UAPI Session::create_webmail_session_for_mail_user function with one exception. This function requires a correct password to create the Webmail session. If you use an incorrect password or attempt to connect to a suspended account, the login will fail.

Examples 


 cPanel Session URL
https://hostname.example.com:2083/cpsess##########/execute/Session/create_webmail_session_for_mail_user?login=username&domain=example.com&password=luggage123456&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 with a password for a cPanel user to connect to Webmail.
$variable = $cpanel->uapi(
    'Session', 'create_webmail_session_for_mail_user',
    array(
		'login'			 => 'username',
		'domain'		 => 'example.com',
		'password'		 => 'luggage123456',
        '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 with a password for a cPanel user to connect to Webmail.
my $variable = $cpliveapi->uapi(
    'Session', 'create_webmail_session_for_mail_user',
    {
		'login'			 => 'username',
		'domain'		 => 'example.com',
		'password'		 => 'luggage123456',
        '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_webmail_user 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 account's username.

A valid Webmail username for the specified domain value.username
domainstring

Required 

The domain for the Webmail account.

A valid domain for the specific login value.example.com
passwordstring

Required

The password for the Webmail account.

A valid password.luggage123456
localestring

The locale that the new session will use.

This parameter defaults to the cPanel user's locale.

A valid locale.

Note:

You must only enter lowercase characters.

en
remote_addressstring

The session's account's client IP address.

Note:

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

This parameter defaults to the authenticated 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 Webmail server's hostname.

  • A valid hostname.
  • undef

    Note:

    The function returns the undef value when:

    • The Webmail server is the server that answers the API call.
    • The Webmail server is not remote.
hostname.example.com

How to use this API

After you successfully call this API, you will need to log in to Webmail. To do this, 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