atmail’s API

APIs have become more common over the last decade, with more applications moving to the web and, more recently, into the cloud. This post will overview the reasons behind choosing to use an API – both from an administrative/developer point of view and from a customer/end-user point of view. We will also take a deeper dive into how to use our atmail API, along with some practical examples that should help you get started with managing your atmail instance. But first…

 

What is an API?

At its most basic, the acronym ‘API’ stands for Application Programming Interface. An API can be public or private, and it defines the rules for how your application works.

MuleSoft has an excellent video to help explain the concept. In their words, “an API is the messenger that takes requests and tells a system what you want to do, and then returns the response to you. To give you a familiar example, think of an API as a waiter in a restaurant. Imagine you’re sitting at the table, with a menu of choices to order from. In the kitchen is the part of the system which will prepare your order. What’s missing is the critical link between communicating your order to the kitchen and delivering your food back to your table. That’s where the waiter (or API) comes in.”

 

Why use an API?

One of the most significant advantages of using and providing an API is automating some of an application’s core functions. Some of these core applications include:

• Authentication of users
• The listing, creating, updating, and deleting of admin roles
• The listing, creating, updating, and deleting of end-user accounts
• The listing, creating, updating, and deleting of user aliases
• The listing, creating, and deleting of domains

The programmatic automation of these tasks allows the email administrator to manage their system with quick and easy command-line utilities, and integrate the atmail email system with any number of other utilities and programs in use. One of the more common uses for this automation is the billing system that a customer uses. Most billing systems allow actions to trigger events on a remote system, allowing the automatic creation of an email account in the atmail system when a user signs up for an account with their provider (our direct customer), and thus reducing our customer’s administrative workload to provision new users.

A primary benefit of allowing this automation is removing potential barriers to your end users. This is often seen as a by-product, but it is actually a critical part of the process, because our customers often already have an existing portal for their customers. Through the API, they can include access to their email or calendars within their current environment, we well as direct login to their accounts through any number of Single Sign On (SSO) mechanisms. This ability to integrate into their existing systems is a key component of offering an easy-to-administer, white label, email solution.

 

atmail API: Overview

atmail has always placed an important focus on User Experience (UX). How people use our software is essential to us, and the UX with email isn’t an easy nut to crack. Because of email’s longevity, nearly everyone using email today has some expectation of how email should behave, based on the years they have spent using it to date; they already have a user experience in mind.

Our API provides the best of both worlds for our customers. They can: provide a proven user experience as is or brand the system as their own (while still maintaining our UX) or integrate our system into their own through our atmail API. These options empower innovation and allow us to see new ways in which people use email. From atmail’s perspective, our customers’ ability to create their own experiences with our software is a considerable benefit.

 

atmail API: Technical

Now that we’ve seen a glimpse into how we think of the API, let’s take a closer look at how we can use it.

First, some caveats: this post is meant to be a primer of sorts, but it is also meant to be a practical guide to using the atmail API. Some of the examples shown may have snippets of code that will assume certain results and are examples that I use (in what can be referred to as a “quick and dirty” method) to get the job done. I welcome any feedback on how to accomplish the same thing differently, and I am always interested in seeing how others are using our atmail API.

This will be using examples from a test account created in our U.S. public cloud. We’ll cover looking at the administrator users and roles, and the end-user email accounts and how to manage them.

If, after reading this post, you would like more details and examples, I invite you to visit our atmail help centre.

 

Authenticate

First, let’s make sure we can authenticate to the cloud. We do this by passing the username and password to the atmail API using the curl command. What we are looking for is “Authentication success”.

Jasons-MBP:~ jasonb$ curl -s -u 'apitest.atmailcloud.com:XXXXXXXXXX' "https://admin.us-east.atmailcloud.com/index.php/api/users/authenticate/"
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0"><authenticate><status>success</status><response><message>Authentication success</message><results></results></response></authenticate></api> 

If you were to pass the incorrect details, or if the admin user you are connecting with doesn’t exist, you will get the following “Authentication failed” message.

Jasons-MBP:~ jasonb$ curl -s -u 'apitset.atmailcloud.com:XXXXXXXXXX' "https://admin.us-east.atmailcloud.com/index.php/api/users/authenticate/"
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0"><authenticate><status>failed</status><response><message>Authentication failed</message><results></results></response></authenticate></api>

Now that we know we can successfully authenticate to the cloud, let’s look at the admin accounts and roles.

 

List admin accounts

Let’s get a list of the administrator accounts on the system. We will take a look at a few more command-line utilities to make this a little more readable.  


xmllint – The xmllint program parses the curl command’s output, formatting this into a more human-readable response.


grep – We’ll use grep to filter out most of what we don’t need from the curl command’s output.


We are interested in the userID and the username values from the output.

Jasons-MBP:~ jasonb$ curl -s -u 'apitest.atmailcloud.com:XXXXXXXXXX' "https://admin.us-east.atmailcloud.com/index.php/api/users/list/" | xmllint -format -
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
 <userlist>
  <status>success</status>
  <response>
   <message/>
   <results>
    <key_0>
     <userId>674</userId>
     <leftEdge>1182</leftEdge>
     <rightEdge>1183</rightEdge>
     <createdByUserId>673</createdByUserId>
     <username>HelpdeskAPI</username>
     <password>{SSHA256}LToSwdTX45Hs5vUEZ/fVMqy2S5zFgVRhI/F4cq4ablEiDaCQVugx0jhUC/bkPBvfPEs1Xu8PXhAbOcUnjXA4KQ==</password>
     <numUsers>8</numUsers>
     <company>atmail</company>
     <fullname>Helpdesk API</fullname>
     <emailAddress>[email protected]</emailAddress>
     <dateCreate>2020-12-07 18:08:52</dateCreate>
     <lastLogin/>
     <modified/>
     <ipAddress/>
     <quota>250</quota>
     <language/>
     <cssColorTheme>darkblue</cssColorTheme>
     <welcomeDisplayed>0</welcomeDisplayed>
     <passwordSetOn>2020-12-07 18:08:52</passwordSetOn>
     <elevateDataAccess>0</elevateDataAccess>
    </key_0>
    <key_1>
     <userId>675</userId>
     <leftEdge>1184</leftEdge>
     <rightEdge>1185</rightEdge>
     <createdByUserId>673</createdByUserId>
     <username>MarketingAPI</username>
     <password>{SSHA256}I1VUEKNoHaQSHaDWLWvdZnWtHzKnRTcn94vmCuZVx1nU9Hi07raBt3KS04yDYVtmCyCiYwCfyA5fK7yTbnRDcw==</password>
     <numUsers>8</numUsers>
     <company>atmail</company>
     <fullname>API Marketing</fullname>
     <emailAddress>apimark[email protected]</emailAddress>
     <dateCreate>2020-12-07 18:10:44</dateCreate>
     <lastLogin/>
     <modified/>
     <ipAddress/>
     <quota>250</quota>
     <language/>
     <cssColorTheme>darkblue</cssColorTheme>
     <welcomeDisplayed>0</welcomeDisplayed>
     <passwordSetOn>2020-12-07 18:10:44</passwordSetOn>
     <elevateDataAccess>0</elevateDataAccess>
    </key_1>
   </results>
  </response>
 </userlist>
</api>

We can grep the username and userId from the list as well.

Jasons-MBP:~ jasonb$ curl -s -u 'apitest.atmailcloud.com:XXXXXXXXXX' "https://admin.us-east.atmailcloud.com/index.php/api/users/list/" | xmllint -format - | grep 'userId\|username'
     <userId>674</userId>
     <username>HelpdeskAPI</username>
     <userId>675</userId>
     <username>MarketingAPI</username>

You will notice that the output does not show the main admin for the account, in this case, apitest.atmailcloud.com. In the example above, I created the users HelpdeskAPI and MarketingAPI from the atmail web admin GUI. While you don’t see the username in the list output from the command, you will see that the createdByUserId tag shows the admin user’s userId value.

<createdByUserId>673</createdByUserId>

 

Roles

atmail deploys a policy-neutral, access-control mechanism, defined around roles and privileges, commonly referred to as Role Based Access Control (RBAC). These policies allow the main administrative account to create sub-administrator accounts, with only the privileges required for their role. Let’s take a look at the roles available in our test account.

Jasons-MBP:~ jasonb$ curl -s -u 'apitest.atmailcloud.com:XXXXXXXXXX' "https://admin.us-east.atmailcloud.com/index.php/api/users/rolelist/" | xmllint -format -
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
 <rolelist>
  <status>success</status>
  <response>
   <message/>
   <results>
    <key_3>
     <roleId>3</roleId>
     <roleName>cloudadmin</roleName>
     <roleDescription>Cloud Account Administrator</roleDescription>
     <roleHierarchy>|1|</roleHierarchy>
     <roleEnabled>1</roleEnabled>
     <isSuperUser>0</isSuperUser>
     <createdByUserId>1</createdByUserId>
     <myRole>1</myRole>
     <children>
      <key_47>
       <roleId>47</roleId>
       <roleName>APIHelpdesk</roleName>
       <roleDescription>Helpdesk user for the API test account</roleDescription>
       <roleHierarchy>|1||3|</roleHierarchy>
       <roleEnabled>1</roleEnabled>
       <isSuperUser>0</isSuperUser>
       <createdByUserId>673</createdByUserId>
       <myRole>0</myRole>
      </key_47>
      <key_48>
       <roleId>48</roleId>
       <roleName>APIMarketing</roleName>
       <roleDescription>Marketing user for API admin</roleDescription>
       <roleHierarchy>|1||3|</roleHierarchy>
       <roleEnabled>1</roleEnabled>
       <isSuperUser>0</isSuperUser>
       <createdByUserId>673</createdByUserId>
       <myRole>0</myRole>
      </key_48>
     </children>
    </key_3>
   </results>
  </response>
 </rolelist>
</api>

There is a lot of information available here. We will need the roleId and the roleName for the next examples, where we will create an admin user and assign it a role. You can see that a role description (roleDescription) was added. I encourage this when creating administrative accounts as it helps get a much better “at a glance” idea of what the roles’ function is. 


Within each of the users’ roles, have defined a set of permissions. The full list of these permissions is very lengthy, and I will leave it as an exercise to the reader to look at the full list of permissions as defined within their account. You can do this with the following command.

Jasons-MBP:~ jasonb$ curl -s -u 'apitest.atmailcloud.com:XXXXXXXXXX' "https://admin.us-east.atmailcloud.com/index.php/api/users/permissionlist/" | xmllint -format -
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
 <permissionlist>
  <status>success</status>
  <response>
   <message/>
   <results>
    <key_0>
     <permissionId>2</permissionId>
     <permissionName>account.add</permissionName>
     <permissionDescription>Right to add accounts</permissionDescription>
     <roles>
      <key_0>APIHelpdesk</key_0>
      <key_1>cloudadmin</key_1>
     </roles>
    </key_0>

Now that we know what the admin users and roles section of the API looks like, let’s look at the domains available on the system to add another admin user.



Listing available domains

Each admin needs to have at least one domain assigned to it when created. We can view the list of available domains with the following command.

Jasons-MBP:~ jasonb$ curl -s -u 'apitest.atmailcloud.com:XXXXXXXXXX' "https://admin.us-east.atmailcloud.com/index.php/api/domain/list/" | xmllint -format -
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
 <domainlist>
  <status>success</status>
  <response>
   <message/>
   <results>
    <key_0>
     <domainId>2763</domainId>
     <brandId>1874</brandId>
     <createdByUserId>11</createdByUserId>
     <cloudCustomersId>322</cloudCustomersId>
     <domainName>apitest.atmailcloud.com</domainName>
     <domainEnabled>1</domainEnabled>
     <domainEnabledPrev>1</domainEnabledPrev>
     <migrateStatus>Migrated</migrateStatus>
     <cosProfileId/>
     <totalUsers>2</totalUsers>
    </key_0>
   </results>
  </response>
 </domainlist>
</api>

Here we can see that we only have one domain available, apitest.atmailcloud.com and the domainId, 2763.



Adding an admin user

To add an administrator user to the system, we need the following details:


• Admin username (username) = Marketing2API
• Admin password (password) = XXXXXXXXXX
• Role identification number we want to assign to the admin user, in this case, we’re going to use the APIMarketing role (roleId) = 48
• The domain or domains the admin user has access to, in this case, we’re going to use apitest.atmailcloud.com (domainId[]) = 2763

You can also add:

• a company name;
• the number of users the admin can add to the system;
• the total disk quota the user can allocate for the users they can add;
• the admin user’s full name; and
• the admin user’s email address.

In the following example, we won’t be assigning an allowed quota or an authorised number of users, because the user we are creating won’t have privileges to add users to the system. I am intentionally leaving off the email address. We are creating the user for someone in the marketing department to access the system’s branding function. As different users may fulfil this role over time, it will be easier to manage the admin user’s contact details through the alias function of atmail. It will allow us to demonstrate the update function of the API.

Jasons-MBP:~ jasonb$ curl -s --data "username=Marketing2API&password=XXXXXXXXXX&roleId=48&domainIds=2763" -u 'apitest.atmailcloud.com:XXXXXXXXXX' "https://admin.us-east.atmailcloud.com/index.php/api/users/create/" | xmllint -format -
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
 <usercreate>
  <status>success</status>
  <response>
   <message>686</message>
   <results>686</results>
  </response>
 </usercreate>
</api>

The “success” status message shows us that the user was successfully added to the system.



Aliases

Now that we’ve seen how to list the admin users, roles, permissions, and domains, and added a new administrative user to the system, let’s add an alias to the system to use for the marketing department.  


To add an alias to the system, we will need the following details.


• AliasName (string, required) – The local address to divert. In this instance, we are going to use [email protected].
• AliasTo (string, required) – the email address where the alias is pointing. In this example, we are going to use [email protected].
• AliasType (string, required) – Values are Local ( divert a local domain to another user), Deliver ( Deliver to the local user and alias ), or Domain ( Divert one domain to another ). We are going to choose a local alias.

Jasons-MBP:~ jasonb$ curl -s --data "[email protected]&[email protected]&AliasType=Local" -u 'apitest.atmailcloud.com:XXXXXXXXXX' "https://admin.us-east.atmailcloud.com/index.php/api/aliases/create/" | xmllint -format -
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
 <aliasescreate>
  <status>success</status>
  <response>
   <message>Success</message>
   <results>
    <key_0>
     <id>13524</id>
    </key_0>
   </results>
  </response>
 </aliasescreate>
</api>

A success status message shows that the alias was created.



List Aliases

Now that we’ve added the alias to the system, let’s update our newly created marketing admin user with an email address. First, let’s look at how we can list the aliases available to us. I’ve highlighted the marketing alias in bold.

Jasons-MBP:~ jasonb$ curl -s -u 'apitest.atmailcloud.com:XXXXXXXXXX' "https://admin.us-east.atmailcloud.com/index.php/api/aliases/list/" | xmllint -format -
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
 <aliaseslist>
  <status>success</status>
  <response>
   <message/>
   <results>
    <key_0>
     <AliasName>[email protected]</AliasName>
     <AliasTo>[email protected]</AliasTo>
     <Domain/>
     <DateCreate>2020-12-07 17:44:57</DateCreate>
     <id>13509</id>
     <aliasType>Local</aliasType>
     <DomainPart>apitest.atmailcloud.com</DomainPart>
    </key_0>
    <key_1>
     <AliasName>[email protected]</AliasName>
     <AliasTo>[email protected]</AliasTo>
     <Domain/>
     <DateCreate>2020-12-07 17:44:57</DateCreate>
     <id>13508</id>
     <aliasType>Local</aliasType>
     <DomainPart>apitest.atmailcloud.com</DomainPart>
    </key_1>
    <key_2>
     <AliasName>[email protected]</AliasName>
     <AliasTo>[email protected]</AliasTo>
     <Domain/>
     <DateCreate>2020-12-14 21:10:39</DateCreate>
     <id>13524</id>
     <aliasType>Local</aliasType>
     <DomainPart>apitest.atmailcloud.com</DomainPart>
    </key_2>
    <key_3>
     <AliasName>[email protected]</AliasName>
     <AliasTo>[email protected]</AliasTo>
     <Domain/>
     <DateCreate>2020-12-07 17:44:57</DateCreate>
     <id>13507</id>
     <aliasType>Local</aliasType>
     <DomainPart>apitest.atmailcloud.com</DomainPart>
    </key_3>
   </results>
  </response>
 </aliaseslist>
</api>

 

Update admin user

Next, we need to confirm the admin user’s userId with our list aliases command, grepping out only the usernames and userIds

Jasons-MBP:~ jasonb$ curl -s -u 'apitest.atmailcloud.com:XXXXXXXXXX' "https://admin.us-east.atmailcloud.com/index.php/api/users/list/" | xmllint -format - | grep 'userId\|username'
     <userId>674</userId>
     <username>HelpdeskAPI</username>
     <userId>675</userId>
     <username>MarketingAPI</username>
     <userId>686</userId>
     <username>Marketing2API</username>

Once we have the userId, and the alias we want to add as the user’s email address, we can update the user.

Jasons-MBP:~ jasonb$ curl -s --data "userId=675&[email protected]" -u "apitest.atmailcloud.com:XXXXXXXXXX" "https://admin.us-east.atmailcloud.com/index.php/api/users/update/" | xmllint -format -
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
  <userupdate>
    <status>success</status>
    <response>
      <message/>
      <results>675</results>
    </response>
  </userupdate>
</api>

The success status message now shows us that the user is updated. I will leave it as an exercise to the reader to list the admin user to verify the email address.

Conclusion

The atmail cloud API is a powerful tool that allows manipulation of our customers’ instances within the cloud, while at the same time, allowing the core functions to be maintained as required. These functions benefit our 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. 

 

Further reading

Practical uses for the atmail API

 

New to atmail?

atmail is an email solutions company with 22 years of global, email expertise. You can trust us to deliver an email hosting platform that is secure, stable and scalable. We power more than 170 million mailboxes worldwide and offer modern, white-labelled, cloud hosted email with your choice of US or (GDPR compliant) EU data centres.