Practical uses for the atmail API

Now that we’ve taken a look at what the atmail API is and some of its basic functions, let’s take a deeper dive into something that you, as an admin, might need to do regularly. We will look at: how to generate a list of users on the system; whether they are active, inactive, or marked for deletion; and then use it to create a CSV file that can be used to sort and filter your results for easier viewing or inclusion in a report.

 

Tools Required

We’re going to use one of the tools we used in our previous article, as well as look into a new one.

curl – This is a command line tool that is powered by libcurl to transfer data from or to a server, using one of the supported protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET and TFTP). The command is designed to work without user interaction.

XMLStarlet – This is a set of command-line utilities (tools) which can be used to transform, query, validate, and edit XML documents and files, using a simple set of shell commands in a similar way that it is done for plain text files using UNIX grep, sed, awk, diff, patch, join, etc commands. This set of command-line utilities can be used by those who deal with many XML documents on UNIX shell command prompt and automated XML processing with shell scripts.

We’ll use curl to fetch the data from the atmail cloud and XMLStarlet to help us filter the curl’s output.

 

Breakdown of the commands used

curl --silent -u "sechub.atmailcloud.com:XXXXXXXXXX" https://admin.pc3.atmailcloud.com/index.php/api/accounts/list |\
xmlstarlet sel -T -t -m '//api/accountlist/response/results/*' -v "concat( userStatus, ',' ,username,',' ,firstName, ',' ,lastName)" -n > users.csv

 

Now, that is a lot to process all at once, so we’ll break it down.

We’re using the curl command to pass along our username and password to the atmailcloud API’s list account function.

We’ll then use a system pipe to the xmlstarlet to filter the results based on what we’re looking for. In this case, it’s the user’s status (active, disabled, or marked for deletion), the username (the email address of the account), and the first and last name of the account holder. We will then use a file redirection to write the data to a Comma Separated Value (CSV) file for later use.

 

Let’s look a bit closer at each of the commands.

First, we’re going to grab the data with curl:

curl --silent -u "sechub.atmailcloud.com:XXXXXXXXXX" https://admin.pc3.atmailcloud.com/index.php/api/accounts/list 

A more thorough breakdown of the command:

curl – The curl command to fetch the data

–silent – silent or quiet mode. Don’t show progress meter or error messages. It makes curl mute. It will still output the data you ask for, potentially even to the terminal/stdout, unless you redirect it.

-u “sechub.atmailcloud.com:XXXXXXXXXX” – The -u flag is used to pass username and password data with curl.

https://admin.pc3.atmailcloud.com/index.php/api/accounts/list — This is the URL of the atmail cloud API that we are using curl to connect to.

The output of the following command is a bit of a mess to try and parse.

[root@mailtps ~]# curl -u "sechub.atmailcloud.com:XXXXXXXXXX" "https://admin.pc3.atmailcloud.com/index.php/api/accounts/list"
<!--?xml version="1.0" encoding="UTF-8"?-->
[email protected] 05:12:432020-05-03 15:10:252Migrated10240102401AdminAccount/var/atmail/users/vol1/c/3/0/3728a8bd-8d50-11ea-a442-0eb4145c9ba8
/[email protected] 05:10:512021-03-23 05:10:510Migrated10240102401BillieLark/var/atmail/users/vol1/2/5/8/232a6ba5-8b96-11eb-a61f-0eb94879b873/[email protected] 
02:35:202021-01-12 02:35:200Migrated10240102401dmarcreporting/var/atmail/users/vol1/7/7/e/d071e204-547e-11eb-a61f-0eb94879b873/[email protected] 05:12:272021-03-23 

Next, we’re going to pipe this through to xmlstarlet. This will clean up the output and provide us with just the results we’re looking for:

| xmlstarlet sel -T -t -m '//api/accountlist/response/results/*' -v "concat( userStatus, ',' ,username,',' ,firstName, ',' ,lastName)" -n

And a closer look at this part of the command:

xmlstarlet – The xmlstarlet command

sel – This tells xmlstarlet that we plan to extract or filter the data.

-T – The output will be text (it defaults to XML).

-t – The following parameters are part of the output template.

-m — This tells xmlstarlet to iterate over all nodes that match the provided xpath expression, which is “//api/accountlist/response/results/*” in this case.

-v – The output of the value of an xpath expression. In this case, the output will be the userStatus, username, firstName, and lastName of the account in question.

-n – This adds a newline character to the end of each account found by the command. If we omitted this flag, the output would be one continuous string and not easy for humans to read.

The output is now much tidier and something we can use to find the number of active and inactive users in our atmailcloud account:

[root@mailtps ~]# curl --silent -u "sechub.atmailcloud.com:XXXXXXXXXX" "https://admin.pc3.atmailcloud.com/index.php/api/accounts/list" | xmlstarlet sel -T -t -m '//api/accountlist/response/results/*' -v "concat( userStatus, ',' ,username,',' ,firstName, ',' ,lastName)" -n
2,[email protected],Admin,Account
0,[email protected],Billie,Lark
0,[email protected],dmarc,reporting
1,[email protected],Frank,Johns
0,[email protected],Jason,Brown
0,[email protected],Jason,Brown
0,[email protected],Jasper,Jones
0,[email protected],Joe,Miller
0,[email protected],John,Prine
0,[email protected],Roger,Doger
0,[email protected],Spam,Dadgnar
0,[email protected],Jason,Spam
0,[email protected],Susan,Miller
0,[email protected],Ta,Co
0,[email protected],,
0,[email protected],,
0,[email protected],Tom,Smith
0,[email protected],Tom,Jones
0,[email protected],Tonya,Timms

You can see that this is quite a difference. Let’s take a look at a couple of lines of the output:

2,[email protected],Admin,Account
0,[email protected],Billie,Lark

The first value is the status of the user. For the atmailcloud, a value of “2” means the account has been marked for deletion, a value of “1” means the user is disabled, and a value of “0” indicates an active user. The second value is the account or email address. The third value is the first name of the user. The fourth value is the last name of the user.

Now, let’s take all of this and redirect it to a file, users.csv, instead of outputting it to the terminal:

> users.csv

This is a standard file redirection and will create the file users.csv in the directory that you are running the command from, unless you specify an absolute path.

The output of this command should just return you to the command prompt:

[root@mailtps ~]# curl --silent -u "sechub.atmailcloud.com:XXXXXXXXXX" "https://admin.pc3.atmailcloud.com/index.php/api/accounts/list" | xmlstarlet sel -T -t -m '//api/accountlist/response/results/*' -v "concat( userStatus, ',' ,username,',' ,firstName, ',' ,lastName)" -n > users.csv
[root@mailtps ~]#

We can concat the CSV file to verify the values are the same as was directed to the terminal window.

[root@mailtps ~]# cat users.csv
2,[email protected],Admin,Account
0,[email protected],Billie,Lark
0,[email protected],dmarc,reporting
1,[email protected],Frank,Johns
0,[email protected],Jason,Brown
0,[email protected],Jason,Brown
0,[email protected],Jasper,Jones
0,[email protected],Joe,Miller
0,[email protected],John,Prine
0,[email protected],Roger,Doger
0,[email protected],Spam,Dadgnar
0,[email protected],Jason,Spam
0,[email protected],Susan,Miller
0,[email protected],Ta,Co
0,[email protected],,
0,[email protected],,
0,[email protected],Tom,Smith
0,[email protected],Tom,Jones
0,[email protected],Tonya,Timms

I prefer the CSV format here, as it is easily opened in a utility like Excel, and can easily be sorted and formatted or turned into graphs or reports for whatever use you need.

Conclusion

This is another example of how the atmail cloud API is a powerful tool, that allows manipulation of your instances within the cloud, while at the same time allowing the core functions to be maintained as required. These functions benefit you (our valued customers), our product and operations teams, and the product as a whole.

We welcome any further thoughts, questions, or ideas about how to use this utility.

 

Background reading: Overview of atmail’s API (and why use an API?)

 

New to atmail?

atmail is an email solutions company with more than 20 years of global, email expertise. We power more than 170 million mailboxes worldwide and offer modern, white-labelled, cloud hosted email, as well as on-premises email solutions for organisations that need to keep their data in-house.