Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface. It also aims at providing a more modern and intuitive interface.
General syntax to run the command line
$ ./james-cli [OPTION] ENTITY ACTION {ARGUMENT}
where
OPTION: optional parameter when running the command line, ENTITY: represents the entity to perform action on, ACTION: name of the action to perform, ARGUMENT: arguments needed for the action.
Example:
$ ./james-cli --url http://127.0.0.1:9999 domain list
The above command lists all domain names available on domain route at address http://127.0.0.1:9999. It does not require any argument to execute.
The following options can be used:
--url : Without it, the default value is http://127.0.0.1:8000.
When James server's jwt setting is enabled, jwt options are required:
--jwt-token : pass the jwt token directly as plain text. E.g:
$ ./james-cli --url http://127.0.0.1:8000 --jwt-token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJlc24iLCJhZG1pbiI6dHJ1ZSwiaWF0IjoxNjA0Mjg3OTU3fQ.IY3AWg9lQE4muXg8iRu1nbluTm786_6aLcoEylCGcbtGcEOp81Neani1-_17xGp2aF6kxBJva0_f_ADUplhfirGXwoxM8evcsdmQBhNGDfa-oXT_a-dd6n7MMPweGOFGhjxnTRvNHpyqDcfNuGGGcB8OfzOsN5epWNkhlivk2OSuY8vR8fHB9Es1Oiv1i8D5H93-K5IXParVLpAtj7uLZT9b7G-kjxlQagApH8USx6JlqIjMwhvM--79SrzPKZ2AtM59NfDT4g6GPaMNntQvXr06Xu3Leys97cot2rsXNfXY1OohorXiYiZ66-eMRcQ7pHF-NyS6dlg87rnMQlpKHw domain list
Commands with valid token with admin=true claim should pass James's authentication.
--jwt-from-file : pass the jwt token through a file (such as token.jwt). E.g:
$ ./james-cli --url http://127.0.0.1:8000 --jwt-from-file token.jwt domain list
As for other commands, arguments might be required after the sub-command (ACTION such as list, add and remove).
Note: the command line before ENTITY will be documented as {cli}.
Add a domain to the domain list.
{cli} domain create <domainToBeCreated>
Resource name domainToBeCreated:
Remove a domain from the domain list.
{cli} domain delete <domainToBeDeleted>
Note: Deletion of an auto-detected domain, default domain or of an auto-detected ip is not supported. We encourage you instead to review your domain list configuration.
Check whether a domain exists on the domain list or not.
{cli} domain exist <domainToBeChecked>
Show all domains' name on the list.
{cli} domain list
Show all domains' name on the list.
{cli} domain listAliases <domain>
{cli} domain addAlias <domain> <sourceOfTheAlias>
{cli} domain removeAlias <domain> <sourceOfTheAlias>
Add a user to the user list.
{cli} user create <username> --password
Then the Command Line will prompt users to enter password (password will not be printed on the screen for security):
Enter value for --password (Password):
Resource name representing valid users, hence it should match the criteria at User Repositories documentation
Note: If the user exists already, its password cannot be updated using this. If you want to update a user's password, please have a look at Update a user password.
{cli} user create --force <username> --password
Then the Command Line will prompt users to enter password (password will not be printed on the screen for security):
Enter value for --password (Password):
Resource name representing valid users, hence it should match the criteria at User Repositories documentation
Note: This also can be used to create a new user.
Check whether a user exists on the user list or not.
{cli} user exist <username>
Resource name representing valid users, hence it should match the criteria at User Repositories documentation
Remove a user from the user list.
{cli} user delete <username>
Show all users' name on the list.
{cli} user list
Same as Create, but a user need to exist.
If the user do not exist, then it will be created.
Create a specific mailbox for a user:
{cli} mailbox create <username> <mailboxName>
Resource name username should be an existing user.
Resource name mailboxName should not be empty, nor contain # & % * characters.
To create nested mailboxes, for instance a work mailbox inside the INBOX mailbox, people should use the . separator. E.g: INBOX.work
{cli} mailbox exist <usernameToBeUsed> <mailboxNameToBeTested>
Resource name usernameToBeUsed should be an existing user
Resource name mailboxNameToBeTested should not be empty
{cli} mailbox delete <usernameToBeUsed> <mailboxNameToBeDeleted>
Resource name usernameToBeUsed should be an existing user
Resource name mailboxNameToBeDeleted should not be empty
{cli} mailbox deleteAll <usernameToBeUsed>
Resource name usernameToBeUsed should be an existing user
{cli} mailbox list <usernameToBeUsed>
Resource name usernameToBeUsed should be an existing user
Given a configured source (from) domain and a destination (to) domain, when an email is sent to an address belonging to the source domain, then the domain part of this address is overwritten, the destination domain is then used. A source (from) domain can have many destination (to) domains.
For example: with a source domain james.apache.org maps to two destination domains james.org and apache-james.org, when a mail is sent to admin@james.apache.org, then it will be routed to admin@james.org and admin@apache-james.org
This feature uses Recipients rewrite table and requires the RecipientRewriteTable mailet to be configured.
Note that email addresses are restricted to ASCII character set. Mail addresses not matching this criteria will be rejected.
Show all configured domain mappings
{cli} domain-mapping listAll
With sourceDomain.tld as the value passed to fromDomain resource name, this command will show all destination domains configured to that domain
{cli} domain-mapping list <sourceDomain.tld>
With sourceDomain.tld as the value passed to fromDomain resource name, this command will add a destination domain to that source domain
{cli} domain-mapping create <sourceDomain.tld> <destination.tld>
With sourceDomain.tld as the value passed to fromDomain resource name, this command will remove a destination domain mapped to that domain
{cli} domain-mapping delete <sourceDomain.tld> <destination.tld>
A regex mapping contains a mapping source and a Java Regular Expression (regex) in String as the mapping value. Everytime, if a mail containing a recipient matched with the mapping source, then that mail will be re-routed to a new recipient address which is re written by the regex.
This feature uses Recipients rewrite table and requires the RecipientRewriteTable API to be configured.
The command will add a regex mapping made from mappingSource and regex to RecipientRewriteTable.
{cli} regex-mapping create <mappingSource> <regex>
Where:
The command will remove the regex mapping made from regex and the mapping source mappingSource out of RecipientRewriteTable.
{cli} regex-mapping delete <mappingSource> <regex>
Where:
When a specific email is sent to the mappingSource mail address, every destination addresses will receive it.
This command will add an address mapping to the Recipients rewrite table
{cli} address-mapping create <mappingSource> <destinationAddress>
Type of both parameters are Address.
Remove an address mapping from the Recipients rewrite table
{cli} address-mapping delete <mappingSource> <destinationAddress>
Type of both parameters are Address.
Receiving all mappings of a corresponding user.
{cli} user-mapping list <userAddress>