How can we help?

Watch this space: Upcoming Help Centre Migration


Gmail integration

Dominic -


How do I allow users to add their Gmail accounts?


  • atmail suite.


I would like users to be able to add their Gmail accounts


The atmail API Server allows client integration with Google Gmail using Google OAuth 2.0. OAuth 2.0 allows users to share access to their Gmail account with the API Server, allowing it to act as a proxy to the Gmail IMAP server. Access is restricted to the following:

  • - Read, send, delete, and manage your email
  • - View your email address

Any application that uses OAuth 2.0 to access Google APIs must have authorization credentials that identify the application to Google's OAuth 2.0 server. As an email provider, you will need to obtain OAuth 2.0 client credentials from the Google API Console. This can be achieved using the below.

Creating a Project

  1. Open the Google API Console, and sign in using a Google account.
  2. Create a new project. For this example we will use a project called atmail-gmail.

When adding a Gmail account from webmail, the user will be presented with a user consent screen, requesting access to specific data. The information presented on this screen is what we need to configure. It also presents branding information such as your product name, logo, and provides links to terms of service, privacy policies etc.

  1. With your previously created project selected, open the Credentials page in the API Console.
  2. Select the OAuth consent screen tab.
  3. Fill out any required and optional fields.

Create and install authorization credentials

The following steps explain how to obtain authorization credentials for your project. These credentials are downloaded as a client_secrets.json file, which must be stored securely in a location available only to the API Server.

  1. In the Google API Console, Click Create credentials > OAuth client ID.
  2. Set the application type to Web application.
  3. Under Authorized redirect URIs, enter the GMail callback URL. This will be the base URL of the API Server followed by the GMail Callback endpoint gmailcb, ie http://localhost:3000/oauthcb. The domain used here is required to be a FQDN.
  4. OAuth client created. Note your client id and secret for API configuration.

atmail API Server configuration

Configure the API Server

  1. Create the file /etc/atmail/api/oauth.json in the api directory.

        "outlook": {



        "gmail": {

            "clientId": "xxxxxxxxxxxxxxxxxx",

            "authUrl": "",

            "tokenUrl": "",

            "clientSecret": "xxxxxxxxxxxxxxxxxx",

            "redirectUrl": "http://localhost:3000/oauthcb",

            "scopes": [







  2. Open api.conf and insert the following OAUTH variable. Pass the /etc/atmail/api/oauth.json as the argument. Also add the HEALTH_CHECK variable to assist us in confirming a successful implementation.
    [root@mydomain ~]# vi /etc/atmail/api/api.conf

  3. Stop the apiserver and restart via the command line so we can see verbose output in-case troubleshooting is required.
    [root@mydomain api]# systemctl stop apiserver
    [root@mydomain api]# apiserver -c /etc/atmail/api/api.conf -V -console
  4. Ensure the healthcheck passes, with a line similar to:
    INFO[2017-08-18T10:30:56+10:00] :-) OAUTH Credentials File validated. 
    INFO[2017-08-18T10:30:56+10:00] :-) Health Check Complete

Webadmin configuration

  1. From the Webadmin, click Services->Webmail Settings.
  2. Select your domain from the drop-down box.
  3. Allow Multiple accounts and Google accounts.
  4. Remember to Save Settings.


  1. Login to an existing account via webmail.
  2. Select Settings->Accounts and click Add Another Account.
  3. Select Google and ok.
  4. The browser will then walk through the necessary steps provided by google to provision the account. The first being, selecting which Gmail account you wish to provision.
  5. Unless you have previously verified your app/domain with google, you will be presented with the following during provisioning. Bypass this by accepting the unverified application/domain.
  6. Grant the relevant permissions to the Gmail account.
  7. Once provisioned, you should be redirected back to webmail where your Gmail account will be visible under Available Accounts.


To implement the above, you will need the use of a FQDN with at-least one A record. Google requires this for the Authorized Redirect URIs. This may be an issue if you are testing locally on a VM that does not have a public IP. The easiest way to mitigate this is to update the servers hosts file to point this domain to its-self.

For example, the hostname used for my atmail suite and mailserver is, while the domain used with googles OAUTH is (which has an A record pointing at a random IP that is not the local VM). The servers host file then looks like the following where is the address of the server.

[root@mydomain ~]# cat /etc/hosts   localhost localhost.localdomain localhost4 localhost4.localdomain4
::1         localhost localhost.localdomain localhost6 localhost6.localdomain6

This allows the server to resolve the domains involved which will give true testing results.


Once you have confirmed your service is working. You should remove the HEALTH_CHECK variable from your api.conf and restart the service via systemd:

[root@mydomain ~] # systemctl start apiserver


Contact our support team

+61 (7) 5357 6605