NAV Navbar
Logo
cURL ruby python perl

Introduction

The API is still in Beta. Please note that during this period based on user feedback we may make some large changes which may break compatibility.

Welcome to the Baruwa Enterprise Edition API documentation.

The Baruwa API allows you to manage a Baruwa Server, programmatic way using conventional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or to execute actions. The Baruwa API is organized around REST and uses OAUTH 2.0 authentication. It is therefore possible to use off-the-shelf HTTP clients.

Most of the functionality that you are familiar with in the Baruwa web interface is also available through the API, allowing you to script the complex actions that your situation requires.

The API documentation will start with a general overview about the design and technology that has been implemented, followed by reference information about specific endpoints.

HTTP Requests

Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI. Requests MUST be made using the HTTPS protocol so that traffic is encrypted. The API responds to different methods depending on the action required.

METHOD USAGE
GET For simple retrieval of information. The information you request will be returned as a JSON object. Paged responses will contain links to the next and last pages.
Any request using the GET method is read-only and will not affect any of the objects you are querying.
POST To create a new object, your request should specify the POST method and contain FORM data.
The POST request should include all of the attributes necessary to create a new object. To create a new object, send a POST request to the target endpoint.
PUT To update an object, the PUT method is used.
The PUT method will only update attributes that are different from the current state of the object.
DELETE To remove an object, the DELETE method is used.
This removes the object, this is not reversible.

HTTP Responses

Response for a Single Object

{
   "name": "example.com"
    ...
}

Response for an Object Collection

{
    "items": [
        {
            "name": "example.com"
            ...
        },
        {
            "name": "example.net"
            ...
        }
    ]
}

When a request is successful, a response body will typically be sent back in the form of a JSON object. An exception to this is when a DELETE request is processed, which will result in a successful HTTP 204 status and an empty response body.

4XX Error messages will return a JSON object containing the HTTP error code and the description. 5XX Error messages will be returned as text.

For responses containing multiple items, the JSON object will contain the items key which will hold the items and a links key which contains the links that you can request.

A Meta key contains the meta data.

Errors

HTTP Status Code Summary

HTTP/1.1 200 OK - Everything worked as expected.
HTTP/1.1 401 Unauthorized - OAUTH authentication failed.
HTTP/1.1 403 Forbidden - User not allowed to access this scope.
HTTP/1.1 412 Precondition Failed - Parameters were valid but request failed.
HTTP/1.1 404 Not Found - The requested item doesn't exist.
HTTP/1.1 500, 502, 503, 504 Server errors - something went wrong on the server.

Baruwa uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error on the Baruwa backend.

4XX Error messages will return a JSON object containing the HTTP error code and the description. 5XX Error messages will be returned as text.

Meta

Sample Meta Object

{
    ...
    "meta": {
        "total": 43
    }
    ...
}

In addition to the main resource root, the response may also contain a meta object. This object contains information about the response itself.

The meta object contains a total key that is set to the total number of objects returnable by the request. This has implications on the links object and pagination.

Sample Links Object

{
    ...
    "links": {
        "pages": {
            "last": "https://baruwa.example.com/api/v1/users?page=2",
            "next": "https://baruwa.example.com/api/v1/users?page=2"
        }
    }
    ...
}

The links object is returned as part of the response body when pagination is enabled. By default, 25 objects are returned per page. If the response contains 25 objects or fewer, no links object will be returned. If the response contains more than 25 objects, the first 25 will be returned along with the links object.

The links object contains a pages object. The pages object, in turn, contains keys indicating the relationship of additional pages. The values of these are the URLs of the associated pages. The keys will be one of the following:

Curl Examples

Set and Export the CLIENT_ID and CLIENT_SECRET variables

export CLIENT_ID=28ec8ea4-a9c3-4315-99a9-5e1b170f03ef
export CLIENT_SECRET=iTEueRj9a94U43hl28Pnl6ZtBu3zsRRGdhLC5emF3uR8HjYkhW32ubknjoVa

Throughout this document, some example API requests will be given using the curl command. This will allow us to demonstrate the various endpoints in a simple, textual format.

The names of account-specific references (like Domain IDs, for instance) will be represented by variables. For instance, a Domain ID may be represented by a variable called $DOMAIN_ID. You can set the associated variables in your environment if you wish to use the examples without modification.

The first variables that you should set to get started are your OAuth Client ID and Client Secret. The next section will go over the details of this.

Obtain a Client ID and Client Secret by going to the Apps & API section of the user account you want to use in the web interface. You can use an existing Client ID and Secret if you have already created an application or add an application using the “Register new Application” button. Copy the generated Client ID and Client Secret and use them to set and export the CLIENT_ID and CLIENT_SECRET variables in your environment as shown in the example.

OAuth Authentication

The Baruwa API uses the OAuth 2.0 protocol to authorize calls. OAuth is an industry-standard open standard for authorization used by many companies to provide secure access to protected resources. For details on authentication, see How Baruwa Enterprise Edition uses OAuth 2.0.

In order to interact with the Baruwa API, you or your application must authenticate.

The Baruwa API handles this through OAuth, OAuth allows you to delegate access to your system using read only or write scopes.

Create an Application

Navigate to the Apps & API section of the user account. Click Register new Application to begin the application-creation process.

When you create a new application, Baruwa generates a set of OAuth keys for the application (the keys consist of a client_id and client_secret).

The client_id and client_secret are displayed to you after the application is created, you can view existing keys by clicking the application name in the list in the Apps & API section of the user account.

Get an access token

Example access token request

curl -v -X POST https://baruwa.example.com/api/v1/oauth/token \
-H "Accept: application/json" \
-d "grant_type=password" -d "username=$CLIENT_ID" \
-d "password=$CLIENT_SECRET"

Make a /api/v1/token call using your application’s OAuth keys for username and password values (the keys are the values of your client_id and client_secret).

In the request body, set grant_type to password, username to client_id and password to client_secret. When you make the call, Baruwa generates and returns a new access token.

The token returned is a Bearer Token, to run the examples below you need to set your TOKEN enviroment variable to this token.

Please save this token in a safe place it is only displayed once.

Make an API call

With a valid access token in hand, you’re ready to make API requests.

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

curl -H "Accept: application/json" -H "Authorization: Bearer $TOKEN"

Send a bearer authorization header with your request. This method of authenticating completes the authorization request in the header portion, away from the actual request.

Revoke an access token

Revoke an access token

curl -v -X POST https://baruwa.example.com/api/v1/oauth/revoke \
-H "Accept: application/json" \
-d "token=$TOKEN" -d "username=$CLIENT_ID" \
-d "password=$CLIENT_SECRET"

Make a /api/v1/revoke call using your application’s OAuth keys for username and password values (the keys are the values of your client_id and client_secret).

In the request body, set token to $TOKEN, When you make the call, Baruwa revokes the token and returns an empty response.

Scopes

As mentioned earlier, all Baruwa API end points are protected by Scopes (permissions) in addition to OAuth authorization.

A Scope is a permission setting that specifies access to Baruwa data or process.

The following scopes can be assigned to an OAuth client application:

Name Action Mode Description Account Type Access
act-read Read READ-ONLY Accounts: Read Admin & Domain Admin
act-create Create READ-WRITE Accounts: Create Admin & Domain Admin
act-update Update READ-WRITE Accounts: Update Admin & Domain Admin
act-delete Delete READ-WRITE Accounts: Delete Admin & Domain Admin
dom-read Read READ-ONLY Domains: Read Admin & Domain Admin
dom-create Create READ-WRITE Domains: Create Admin
dom-update Update READ-WRITE Domains: Update Admin & Domain Admin
dom-delete Delete READ-WRITE Domains: Delete Admin & Domain Admin
org-read Read READ-ONLY Organizations: Read Admin
org-create Create READ-WRITE Organizations: Create Admin
org-update Update READ-WRITE Organizations: Update Admin
org-delete Delete READ-WRITE Organizations: Delete Admin
sta-read Read READ-ONLY Status: Read Admin & Domain Admin

Accounts

Account objects are users accounts that are configured on the Baruwa server.

The standard account attributes are:

Attribute Type Description
username String The username for the account
firstname String The first names
lastname String The last names
password1 String This must be a strong password
password2 String This must be a strong password
email String A valid email address
timezone String Users timezone, all dates and times will be displayed in this timezone
account_type Number The account type
domains Number The domains to which this user belongs
active Boolean Enable or disable this entry
send_report Boolean If enabled the user will receive reports from the system, these include quarantine as well as summary reports
spam_checks Boolean Enable or disable spam checking of email sent to and from this users email addresses
low_score Number The score at which an email is considered to be suspected spam.
high_score Number The score at which an email is considered to be definitely spam.
block_macros Boolean Enable or disable blocking Attachments with Macros

List all Accounts

List all Accounts

curl -v -X GET https://baruwa.example.com/api/v1/users \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
api.get_users()
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.get_users()
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample response of list all Accounts

{
    "items": [{
        "username": "fuzzy@example.com",
        "send_report": false,
        "account_type": 3,
        "addresses": [],
        "firstname": "Fuzzy",
        "organizations": [],
        "lastname": "Lumpkins",
        "spam_checks": false,
        "email": "fuzzy@example.com",
        "low_score": 2.0,
        "high_score": 12.0,
        "created_on": "2014:09:20:15:14:30",
        "last_login": "2014:10:03:08:54:28",
        "active": true,
        "timezone": "Africa/Abidjan",
        "local": true,
        "id": 4,
        "domains": [{
            "name": "example.com",
            "id": 4
        }]
    }, {
        "username": "rowdyrough",
        "send_report": false,
        "account_type": 3,
        "addresses": [],
        "firstname": "Rowdy",
        "organizations": [],
        "lastname": "Rough",
        "spam_checks": false,
        "email": "rowdyrough@example.com",
        "low_score": 0.0,
        "high_score": 0.0,
        "created_on": "2014:10:07:06:35:48",
        "last_login": "2014:10:11:22:38:11",
        "active": true,
        "timezone": "Africa/Johannesburg",
        "local": true,
        "id": 5,
        "domains": [{
            "name": "example.com",
            "id": 4
        }]
    }],
    "meta": {
        "total": 2
    }
}

To retrieve a list of all of the users in your account, send a GET request to /api/v1/users. For administrator accounts this will list all the users on the system, for Domain administrators it will contain users within all domains the Domain administrator is administrator for.

The response will be a JSON object with a key called items. The value of this will be an array of Account objects, each of which contain the extended account attributes as described above.

Create a new Account

Create an Account

curl -v -X POST https://baruwa.example.com/api/v1/users \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "username=blossom" \
-d "firstname=Blossom" \
-d "lastname=Utonium" \
-d "password1=ng5qhhbiwozcANc3" \
-d "password2=ng5qhhbiwozcANc3" \
-d "email=blossom@example.com" \
-d "timezone=Africa/Johannesburg" \
-d "account_type=3" \
-d "domains=9" \
-d "active=y" \
-d "send_report=y" \
-d "spam_checks=y" \
-d "low_score=0.0" \
-d "high_score=0.0"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')

data = {
        "username": "blossom",
        "firstname": "Blossom",
        "lastname": "Utonium",
        "password1": "ng5qhhbiwozcANc3",
        "password2": "ng5qhhbiwozcANc3",
        "email": "blossom@example.com",
        "timezone": "Africa/Johannesburg",
        "account_type": "3",
        "domains": "9",
        "active": "y",
        "send_report": "y",
        "spam_checks": "y",
        "low_score": "0.0",
        "high_score": "0.0"}

api.create_user(data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To create a new Account, send a POST request to /api/v1/users.

Set the standard attributes described above.

Retrieve an existing Account

Retrieve an existing Account

curl -v -X GET https://baruwa.example.com/api/v1/users/$USER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

userid = 5

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.get_user(userid)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output retrieve an existing Account

{
    "username": "rowdyrough",
    "send_report": false,
    "account_type": 3,
    "addresses": [],
    "firstname": "Rowdy",
    "organizations": [],
    "lastname": "Rough",
    "spam_checks": false,
    "email": "rowdyrough@example.com",
    "low_score": 0.0,
    "high_score": 0.0,
    "created_on": "2014:10:07:06:35:48",
    "last_login": "2014:10:11:22:38:11",
    "active": true,
    "timezone": "Africa/Johannesburg",
    "local": true,
    "id": 5,
    "domains": [{
        "name": "example.com",
        "id": 4
    }]
}

To get details about a specific account, send a GET request to /api/v1/users/$USER_ID.

The response will be a JSON object that contains the extended attributes defined for an account as described above.

Update an Account

Update an Account

curl -v -X PUT https://baruwa.example.com/api/v1/users \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "username=blossom" \
-d "firstname=Blossom" \
-d "lastname=Utonium" \
-d "password1=ng5qhhbiwozcANc3" \
-d "password2=ng5qhhbiwozcANc3" \
-d "email=blossom@example.com" \
-d "timezone=Africa/Johannesburg" \
-d "account_type=3" \
-d "domains=9" \
-d "send_report=y" \
-d "spam_checks=y" \
-d "low_score=5.5" \
-d "high_score=12.2"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')

data = {
        "username": "blossom",
        "firstname": "Blossom",
        "lastname": "Utonium",
        "password1": "ng5qhhbiwozcANc3",
        "password2": "ng5qhhbiwozcANc3",
        "email": "blossom@example.com",
        "timezone": "Africa/Johannesburg",
        "account_type": "3",
        "domains": "9",
        "active": "y",
        "send_report": "y",
        "spam_checks": "y",
        "low_score": "5.0",
        "high_score": "10.0"}

api.update_user(data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To update an Account, send a PUT request to /api/v1/users/$USER_ID.

Delete an Account

Delete an existing Account

curl -v -X DELETE https://baruwa.example.com/api/v1/users/$USER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

userid = 10

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.delete_user(userid)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To delete an Account, send a DELETE request to /api/v1/users/$USER_ID.

The Account will be deleted and the response status will be a 204. This indicates a successful request with no body returned

Passwords

Domain administrator and normal user account passwords can be changed using the API, administrator accounts can only be changed using the command line.

Change a password

Change an Account password

curl -v -X POST https://baruwa.example.com/api/v1/users/chpw/$USER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "password1=Hp9hzcd1grdSqtrn" \
-d "password2=Hp9hzcd1grdSqtrn"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To change an Account password, send a POST request to /api/v1/users/chpw/$USER_ID.

The password will be changed and the response status will be a 204. This indicates a successful request with no body returned

Alias Addresses

Alias Addresses are added to users accounts on the Baruwa server to enable the user to access email from or to email aliases that belong to them.

Create an Alias Address

Create an Alias Address

curl -v -X POST https://baruwa.example.com/api/v1/aliasaddresses/$USER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=info@example.com" \
-d "enabled=y"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

userid = 2
data = {
    "enabled": "y",
    "address": "info@example.com"
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.create_alias(userid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output from Create an Alias Address

{
    "enabled": true,
    "id": 3,
    "address": "info@example.com"
}

To create an Alias Address, send a POST request to /api/v1/aliasaddresses/$USER_ID

Retrieve an existing Alias Address

Retrieve an existing Alias Address

curl -v -X GET https://baruwa.example.com/api/v1/aliasaddresses/$ADDRESS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

addressid = 3

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.get_aliases(addressid)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output from Retrieve an existing Alias Address

{
    "enabled": true,
    "id": 3,
    "address": "info@example.com"
}

To retrieve an existing Alias Address, send a GET request to /api/v1/aliasaddresses/$ADDRESS_ID

Update an Alias Address

Update an Alias Address

curl -v -X PUT https://baruwa.example.com/api/v1/aliasaddresses/$ADDRESS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=info@example.com" \
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

addressid = 3
data = {
    "address": "info@example.com"
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.update_alias(addressid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output from Update an Alias Address

{
    "enabled": false,
    "id": 3,
    "address": "info@example.com"
}

To update an Alias Address, send a PUT request to /api/v1/aliasaddresses/$ADDRESS_ID

Delete an Alias Address

Delete an Alias Address

curl -v -X DELETE https://baruwa.example.com/api/v1/aliasaddresses/$ADDRESS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=info@example.com" \
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

addressid = 3
data = {
    "address": "info@example.com"
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.delete_alias(addressid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To delete an Alias Address, send a DELETE request to /api/v1/aliasaddresses/$ADDRESS_ID

The Alias Address will be deleted and the response status will be a 204. This indicates a successful request with no body returned

Domains

Domain resources are domain names that you have configured to process email for via the Baruwa server.

The standard domain attributes are:

Attribute Type Description
name String Domain name for which email is processed
site_url String Customize the url that is used in links generated for reports for users in this domain. This url needs to be configured to point to this system otherwise it will create incorrect links in the reports. This must be the full base url for example https://antispam.example.com
status Boolean Enable or disable this entry
accept_inbound Boolean Enable or disable accepting of inbound mail to this domain
discard_mail Boolean Discard all mail sent to this domain
smtp_callout Boolean Enable SMTP callout based recipient verification. The recipients of email sent to this domain will be checked on the delivery server(s) configured for the domain
ldap_callout Boolean Enable LDAP email address verification for this domain. If enabled, the recipients of email sent to this domain will be checked aganist an LDAP directory prior to being accepted, you need to have an authentication server entry of type LDAP for this to work correctly.
virus_checks Boolean Enable or disable virus checks for this domain
virus_checks_at_smtp Boolean Run Virus Checks at SMTP time, if disabled virus checks will be ran after SMTP time allowing you to quarantine virus infected messages
block_macros Boolean Enable or disable blocking Attachments with Macros
spam_checks Boolean Enable or disable spam checks for this domain.
spam_actions Number What to do with messages that score at or above the Probable spam score but below the Definite spam score, these scores can be set below
highspam_actions Number What to do with messages that score at or above the Definite spam score, this score can be set below
virus_actions Number What to do with messages that are virus infected
low_score Number The score at which an email is considered to be suspected spam.
high_score Number The score at which an email is considered to be definitely spam.
message_size String The maximum message size for email sent to and from email addresses under this domain, the format is 2B,2K,2M for bytes,kilobytes,megabytes respectively
delivery_mode Number If the domain has more than one server where clean mail is delivered how should the deliveries be done, load balanced and failover delivery is supported
language String The default language for users under this domain
timezone String The default timezone for users under this domain
report_every Number How often PDF reports should be sent
organizations Number The organizations that own this domain. This is the Organisation ID

The following options can be set for spam_actions, highspam_actions, virus_actions:

Value Option Description
1 Deliver Deliver the email to the destination
2 Quarantine Quarantine the email
3 Delete Delete the email

The following options can be set for delivery_mode:

Value Option Description
1 Load balance Load balance the delivery of messages the configured delivery servers
2 Fail over Deliver to one server until it fails then try the others

The following options can be set for report_every:

Value Option Description
0 Disabled Disable the sending of Domain reports
1 Daily Send a Domain report daily
2 Weekly Send a Domain report weekly
3 Monthly Send a Domain report monthly

Domains contain the following extended attributes

The following extended attributes are returned for Delivery Servers. An array is returned and contains an object with the following attributes.

Attribute Type Description
id Number Deliver Server ID
address String Server address
port Number Server Port

The following extended attributes are returned for Authentication Settings. An array is returned and contains an object with the following attributes.

Attribute Type Description
id Number Deliver Server ID
address String Server address
protocol Number Authentication Protocol

The following extended attributes are returned for Alias Domains. An array is returned and contains an object with the following attributes.

Attribute Type Description
id Number Domain Alias ID
name String Domain Alias Name

The following extended attributes are returned for DKIM Keys. An array is returned and contains an object with the following attributes.

Attribute Type Description
id Number DKIM Key ID

The following extended attributes are returned for Domain email signatures. An array is returned and contains an object with the following attributes.

Attribute Type Description
id Number Signature ID
type Number Signature Type 1 for text, 2 for html

List all Domains

List all Domains

curl -v https://baruwa.example.com/api/v1/domains \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample Response

{
    "items": [{
        "signatures": [{
            "type": 1,
            "id": 1
        }],
        "highspam_actions": 2,
        "delivery_mode": 1,
        "virus_checks": true,
        "ldap_callout": false,
        "dkimkeys": [],
        "timezone": "Africa/Johannesburg",
        "spam_actions": 2,
        "id": 2,
        "deliveryservers": [{
            "address": "192.168.1.150",
            "id": 2,
            "port": 25
        }],
        "site_url": "https://mail.example.com",
        "authservers": [{
            "protocol": 2,
            "id": 2,
            "address": "mail.example.com"
        }],
        "report_every": 3,
        "aliases": [{
            "name": "mojo.example.com",
            "id": 2
        }],
        "status": true,
        "accept_inbound": true,
        "discard_mail": false,
        "virus_checks_at_smtp": true,
        "low_score": 10.0,
        "name": "example.com",
        "language": "en",
        "spam_checks": false,
        "smtp_callout": false,
        "message_size": "0",
        "high_score": 20.0,
        "virus_actions": 2
    }, {
        "signatures": [],
        "highspam_actions": 2,
        "delivery_mode": 1,
        "virus_checks": true,
        "ldap_callout": false,
        "dkimkeys": [],
        "timezone": "Africa/Johannesburg",
        "spam_actions": 2,
        "id": 4,
        "deliveryservers": [{
            "address": "192.168.1.150",
            "id": 4,
            "port": 25
        }],
        "site_url": "https://mail.example.net",
        "authservers": [],
        "report_every": 3,
        "aliases": [],
        "status": true,
        "discard_mail": false,
        "virus_checks_at_smtp": false,
        "low_score": 0.0,
        "name": "example.net",
        "language": "en",
        "spam_checks": true,
        "smtp_callout": true,
        "message_size": "0",
        "high_score": 0.0,
        "virus_actions": 2
    }],
    "meta": {
        "total": 2
    }
}

To retrieve a list of all of the domains in your account, send a GET request to /api/v1/domains. For administrator accounts this will list all the domains on the system, for Domain administrators it will contain all domains the Domain administrator is administrator for.

The response will be a JSON object with a key called items. The value of this will be an array of Domain objects, each of which contain the extended domain attributes as described above.

Create a new Domain

Create a Domain

curl -v -X POST https://baruwa.example.com/api/v1/domains \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "name=example.net" \
-d "site_url=http://baruwa.example.net" \
-d "status=y" \
-d "discard_mail=" \
-d "smtp_callout=" \
-d "ldap_callout=" \
-d "virus_checks=y" \
-d "virus_checks_at_smtp=y" \
-d "spam_checks=y" \
-d "spam_actions=3" \
-d "highspam_actions=3" \
-d "virus_actions=3" \
-d "low_score=0.0" \
-d "high_score=0.0" \
-d "message_size=0" \
-d "delivery_mode=1" \
-d "language=en" \
-d "timezone=Africa/Johannesburg" \
-d "report_every=3" \
-d "organizations=1"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample Response

{
    "signatures": [],
    "highspam_actions": 3,
    "delivery_mode": 1,
    "virus_checks": true,
    "ldap_callout": true,
    "dkimkeys": [],
    "timezone": "Africa/Johannesburg",
    "spam_actions": 3,
    "id": 10,
    "deliveryservers": [],
    "site_url": "http://baruwa.example.net",
    "authservers": [],
    "report_every": 3,
    "aliases": [],
    "status": true,
    "discard_mail": false,
    "virus_checks_at_smtp": true,
    "low_score": 0.0,
    "name": "example.net",
    "language": "en",
    "spam_checks": true,
    "smtp_callout": true,
    "message_size": "0",
    "high_score": 0.0,
    "virus_actions": 3
}

To create a new Domain, send a POST request to /api/v1/domains.

Set the standard attributes described above.

Retrieve a Domain

Retrieve an existing Domain

curl -v https://baruwa.example.com/api/v1/domains/$DOMAIN_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample Response

{
    "signatures": [{
        "type": 1,
        "id": 1
    }],
    "highspam_actions": 2,
    "delivery_mode": 1,
    "virus_checks": true,
    "ldap_callout": false,
    "dkimkeys": [],
    "timezone": "Africa/Johannesburg",
    "spam_actions": 2,
    "id": 1,
    "deliveryservers": [{
        "address": "192.168.1.150",
        "id": 2,
        "port": 25
    }],
    "site_url": "https://mail.example.com",
    "authservers": [{
        "protocol": 2,
        "id": 2,
        "address": "mail.example.com"
    }],
    "report_every": 3,
    "aliases": [{
        "name": "mojo.example.com",
        "id": 2
    }],
    "status": true,
    "discard_mail": false,
    "virus_checks_at_smtp": true,
    "low_score": 10.0,
    "name": "example.com",
    "language": "en",
    "spam_checks": false,
    "smtp_callout": false,
    "message_size": "0",
    "high_score": 20.0,
    "virus_actions": 2
}

To get details about a specific domain, send a GET request to /api/v1/domains/$DOMAIN_ID.

The response will be a JSON object that contains the extended attributes defined for a domain as described above.

Retrieve a Domain by Name

Retrieve an existing Domain using the Domain name

curl -v https://baruwa.example.com/api/v1/domains/byname/$DOMAIN_NAME \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample Response

{
    "signatures": [{
        "type": 1,
        "id": 1
    }],
    "highspam_actions": 2,
    "delivery_mode": 1,
    "virus_checks": true,
    "ldap_callout": false,
    "dkimkeys": [],
    "timezone": "Africa/Johannesburg",
    "spam_actions": 2,
    "id": 1,
    "deliveryservers": [{
        "address": "192.168.1.150",
        "id": 2,
        "port": 25
    }],
    "site_url": "https://mail.example.com",
    "authservers": [{
        "protocol": 2,
        "id": 2,
        "address": "mail.example.com"
    }],
    "report_every": 3,
    "aliases": [{
        "name": "mojo.example.com",
        "id": 2
    }],
    "status": true,
    "discard_mail": false,
    "virus_checks_at_smtp": true,
    "low_score": 10.0,
    "name": "example.com",
    "language": "en",
    "spam_checks": false,
    "smtp_callout": false,
    "message_size": "0",
    "high_score": 20.0,
    "virus_actions": 2
}

To get details about a specific domain, send a GET request to /api/v1/domains/byname/$DOMAIN_NAME.

The response will be a JSON object that contains the extended attributes defined for a domain as described above.

Update a Domain

Update a Domain

curl -v -X PUT https://baruwa.example.com/api/v1/domains/$DOMAIN_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "name=example.com" \
-d "site_url=http://baruwa.example.net" \
-d "status=y" \
-d "discard_mail=y" \
-d "smtp_callout=" \
-d "ldap_callout=" \
-d "virus_checks=y" \
-d "virus_checks_at_smtp=y" \
-d "spam_checks=y" \
-d "spam_actions=3" \
-d "highspam_actions=3" \
-d "virus_actions=3" \
-d "low_score=0.0" \
-d "high_score=0.0" \
-d "message_size=0" \
-d "delivery_mode=1" \
-d "language=en" \
-d "timezone=Africa/Johannesburg" \
-d "report_every=3" \
-d "organizations=1"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample response to update Domain

{
    "signatures": [],
    "highspam_actions": 3,
    "delivery_mode": 1,
    "virus_checks": true,
    "ldap_callout": true,
    "dkimkeys": [],
    "timezone": "Africa/Johannesburg",
    "spam_actions": 3,
    "id": 10,
    "deliveryservers": [],
    "site_url": "http://baruwa.example.net",
    "authservers": [],
    "report_every": 3,
    "aliases": [],
    "status": true,
    "discard_mail": true,
    "virus_checks_at_smtp": true,
    "low_score": 0.0,
    "name": "example.com",
    "language": "en",
    "spam_checks": true,
    "smtp_callout": true,
    "message_size": "0",
    "high_score": 0.0,
    "virus_actions": 3
}

To update a Domain, send a PUT request to /api/v1/domains/$DOMAIN_ID.

Delete a Domain

Delete an existing Domain

curl -v -X DELETE https://baruwa.example.com/api/v1/domains/$DOMAIN_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To delete a Domain, send a DELETE request to /api/v1/domains/$DOMAIN_ID.

The Domain will be deleted and the response status will be a 204. This indicates a successful request with no body returned

Domain Aliases

Some organisations have email addressed to the same account using different domain names, Alias domains allow users access to all their messages regardless of the domain name under a single login.

By adding an alias to a domain name, Baruwa will accept and process email for that domain alias as well. This simplifies configuration in cases where an organisation owns multiple domains, for example example.com, example.net and example.org. You can add example.com as a domain and then add the others as domain aliases of example.com

Listing Domain Aliases

Listing all Domain Aliases under a Domain

curl -v -X GET https://baruwa.example.com/api/v1/domainaliases/$DOMAIN_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output from Listing all Domain Aliases under a Domain

{
    "items": [{
        "status": true,
        "domain": {
            "name": "example.com",
            "id": 2
        },
        "id": 2,
        "name": "example.net"
    }],
    "meta": {
        "total": 1
    }
}

To retrieve a list of Domain Aliases assigned to a Domain, send a GET request to /api/v1/domainaliases/$DOMAIN_ID.

Create a Domain Alias

Create a new Domain Alias

curl -v -X POST https://baruwa.example.com/api/v1/domainaliases/$DOMAIN_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "name=example.net" \
-d "status=y" \
-d "domain=2"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output from Create a new Domain Alias

{
    "status": true,
    "domain": {
        "name": "example.com",
        "id": 2
    },
    "id": 4,
    "name": "example.net"
}

To create a Domain Aliases, send a POST request to /api/v1/domainaliases/$DOMAIN_ID.

Retrieve Domain Alias

Retrieve an existing Domain Alias

curl -v -X GET https://baruwa.example.com/api/v1/domainaliases/$DOMAIN_ID/$ALIAS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output from Retrieve an existing Domain Alias

{
    "status": true,
    "domain": {
        "name": "example.com",
        "id": 2
    },
    "id": 4,
    "name": "example.net"
}

To retrieve an existing Domain Alias, send a GET request to /api/v1/domainaliases/$DOMAIN_ID/$ALIAS_ID.

Update a Domain Alias

Update a Domain Alias

curl -v -X PUT https://baruwa.example.com/api/v1/domainaliases/$DOMAIN_ID/$ALIAS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "name=example.net"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output from Update a Domain Alias

{
    "status": false,
    "domain": {
        "name": "example.com",
        "id": 2
    },
    "id": 4,
    "name": "example.net"
}

To update a Domain Alias, send a PUT request to /api/v1/domainaliases/$DOMAIN_ID/$ALIAS_ID.

Delete a Domain Alias

Delete a Domain Alias

curl -v -X DELETE https://baruwa.example.com/api/v1/domainaliases/$DOMAIN_ID/$ALIAS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "name=example.net"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To delete a Domain Alias, send a DELETE request to /api/v1/domainaliases/$DOMAIN_ID/$ALIAS_ID.

The Domain Alias will be deleted and the response status will be a 204. This indicates a successful request with no body returned

Delivery servers

Delivery servers are the actual mail servers hosting the email accounts where messages processed by Baruwa need to be delivered.

Multiple servers per domain are supported and they can be configured to either load balance or fail over.

In load balance mode mail is sent to the group of servers in a round robin manner while in fail over mail is sent to the first in the list and only to the others if the first is not available.

Listing Delivery servers

Listing all Delivery servers for a Domain

curl -v -X GET https://baruwa.example.com/api/v1/deliveryservers/$DOMAIN_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

domainid = 9

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.get_deliveryservers(domainid)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Listing all Delivery servers for a Domain

{
    "items": [{
        "domain": {
            "name": "example.com",
            "id": 2
        },
        "protocol": 1,
        "enabled": true,
        "id": 2,
        "address": "192.168.1.150",
        "port": 25
    }],
    "meta": {
        "total": 1
    }
}

To retrieve a list of Delivery servers configured for a Domain, send a GET request to /api/v1/deliveryservers/$DOMAIN_ID.

Create a Delivery server

Create a new Delivery server

curl -v -X POST https://baruwa.example.com/api/v1/deliveryservers/$DOMAIN_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.151" \
-d "protocol=1" \
-d "port=25" \
-d "require_tls=n" \
-d "enabled=y"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

domainid = 9
data = {
    "address": "192.168.1.152",
    "protocol": "1",
    "port": "25",
    "require_tls": "n",
    "enabled": "y"
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.create_deliveryserver(domainid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Create a new Delivery server

{
    "domain": {
        "name": "example.com",
        "id": 2
    },
    "protocol": 1,
    "enabled": true,
    "require_tls": false,
    "id": 9,
    "address": "192.168.1.151",
    "port": 25
}

To create a new Delivery server, send a POST request to /api/v1/deliveryservers/$DOMAIN_ID.

Retrieve a Delivery server

Retrieve an existing Delivery server

curl -v -X GET https://baruwa.example.com/api/v1/deliveryservers/$DOMAIN_ID/$SERVER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

domainid = 9
serverid = 4

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.get_deliveryserver(domainid, serverid)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Retrieve an existing Delivery server

{
    "domain": {
        "name": "example.com",
        "id": 2
    },
    "protocol": 1,
    "enabled": true,
    "require_tls": false,
    "id": 9,
    "address": "192.168.1.151",
    "port": 25
}

To retrieve an existing Delivery server, send a GET request to /api/v1/deliveryservers/$DOMAIN_ID/$SERVER_ID.

Update a Delivery server

Update a Delivery server

curl -v -X PUT https://baruwa.example.com/api/v1/deliveryservers/$DOMAIN_ID/$SERVER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.151" \
-d "protocol=1" \
-d "port=25"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

domainid = 9
serverid = 4
data = {
    "address": "192.168.1.153",
    "protocol": "1",
    "port": "25",
    "require_tls": "n",
    "enabled": "y"
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.update_deliveryserver(domainid, serverid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output from Update a Delivery server

{
    "domain": {
        "name": "example.com",
        "id": 2
    },
    "protocol": 1,
    "enabled": false,
    "require_tls": false,
    "id": 9,
    "address": "192.168.1.151",
    "port": 25
}

To update a Delivery server, send a PUT request to /api/v1/deliveryservers/$DOMAIN_ID/$SERVER_ID.

Delete a Delivery server

Delete a Delivery server

curl -v -X DELETE https://baruwa.example.com/api/v1/deliveryservers/$DOMAIN_ID/$SERVER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.151"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

domainid = 9
serverid = 4
data = {
    "address": "192.168.1.153",
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.delete_deliveryserver(domainid, serverid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To delete a Delivery server, send a DELETE request to /api/v1/deliveryservers/$DOMAIN_ID/$SERVER_ID.

The Delivery server will be deleted and the response status will be a 204. This indicates a successful request with no body returned

Authentication Settings

Authentication settings allow users within a domain be be authenticated to an external authentication system.

This can be used for centralised user management and to allow users to use existing authentication credentials instead of creating duplicate accounts on the Baruwa system.

The supported external authentication mechanisms include:

The AD/LDAP mechanism allows for the user details in the directory to be automatically updated to the Baruwa account created for them. These details include:

Listing Authentication Settings

Listing all Authentication Settings for a Domain

curl -v -X GET https://baruwa.example.com/api/v1/authservers/$DOMAIN_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

domainid = 9

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
get_authservers(domainid)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Listing all Authentication Settings for a Domain

{
    "items": [{
        "protocol": 2,
        "enabled": true,
        "user_map_template": "example_%(user)s",
        "split_address": true,
        "address": "192.168.1.150",
        "id": 2
    }],
    "meta": {
        "total": 1
    }
}

To retrieve a list of Authentication Settings configured for a Domain, send a GET request to /api/v1/authservers/$DOMAIN_ID.

Create Authentication Settings

Create Authentication Settings for a Domain

curl -v -X POST https://baruwa.example.com/api/v1/authservers/$DOMAIN_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.151" \
-d "protocol=2" \
-d "port=993" \
-d "enabled=y" \
-d "split_address=y" \
-d "user_map_template=example_%(user)s"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

domainid = 9
data = {
    "address": "192.168.1.151",
    "protocol": "2",
    "port": "993",
    "enabled": "y",
    "split_address": "y",
    "user_map_template": "example_%(user)s"
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.create_authserver(domainid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Create Authentication Settings for a Domain

{
    "protocol": 2,
    "enabled": true,
    "user_map_template": "example_%(user)s",
    "split_address": true,
    "address": "192.168.1.151",
    "id": 5
}

To create Authentication Settings, send a POST request to /api/v1/authservers/$DOMAIN_ID.

Retrieve Authentication Settings

Retrieve existing Authentication Settings

curl -v -X GET https://baruwa.example.com/api/v1/authservers/$DOMAIN_ID/$SERVER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

domainid = 9
serverid = 4

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.get_authserver(domainid, serverid)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Retrieve existing Authentication Settings

{
    "protocol": 2,
    "enabled": true,
    "user_map_template": "example_%(user)s",
    "split_address": true,
    "address": "192.168.1.151",
    "id": 5
}

To retrieve existing Authentication Settings, send a GET request to /api/v1/authservers/$DOMAIN_ID/$SERVER_ID.

Update Authentication Settings

Update Authentication Settings

curl -v -X PUT https://baruwa.example.com/api/v1/authservers/$DOMAIN_ID/$SERVER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.151" \
-d "protocol=2" \
-d "port=993" \
-d "enabled=y" \
-d "split_address=y" \
-d "user_map_template="
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

domainid = 9
serverid = 3
data = {
    "address": "192.168.1.151",
    "protocol": "2",
    "port": "995",
    "enabled": "y",
    "split_address": "y",
    "user_map_template": "example_%(user)s"
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.update_authserver(domainid, serverid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output from Update Authentication Settings

{
    "protocol": 2,
    "enabled": true,
    "user_map_template": "",
    "split_address": true,
    "address": "192.168.1.151",
    "id": 5
}

To update Authentication Settings, send a PUT request to /api/v1/authservers/$DOMAIN_ID/$SERVER_ID.

Delete Authentication Settings

Delete Authentication Settings

curl -v -X DELETE https://baruwa.example.com/api/v1/authservers/$DOMAIN_ID/$SERVER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.151" \
-d "protocol=2" \
-d "port=993" \
-d "enabled=y" \
-d "split_address=y" \
-d "user_map_template="
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

domainid = 9
serverid = 3
data = {
    "address": "192.168.1.151",
    "protocol": "2",
    "port": "995",
    "enabled": "y",
    "split_address": "y",
    "user_map_template": "example_%(user)s"
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.delete_authserver(domainid, serverid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To delete a Authentication Settings, send a DELETE request to /api/v1/authservers/$DOMAIN_ID/$SERVER_ID.

The Delivery server will be deleted and the response status will be a 204. This indicates a successful request with no body returned

AD/LDAP Settings

AD/LDAP authentication requires the following additional setting.

Create AD/LDAP Settings

Create AD/LDAP Settings

curl -v -X POST https://baruwa.example.com/api/v1/ldapsettings/$DOMAIN_ID/$SERVER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "basedn=ou=Users,dc=example,dc=com" \
-d "nameattribute=uid" \
-d "emailattribute=mail" \
-d "binddn=uid=readonly-admin,ou=Users,dc=example,dc=com" \
-d "bindpw=P4ssW0rd" \
-d "usetls=y" \
-d "search_scope=subtree" \
-d "emailsearch_scope=subtree"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Create LDAP Settings

{
    "binddn": "uid=readonly-admin,ou=Users,dc=example,dc=com",
    "emailsearchfilter": "",
    "emailsearch_scope": "subtree",
    "searchfilter": "",
    "search_scope": "subtree",
    "authserver": {
        "id": 6
    },
    "basedn": "ou=Users,dc=example,dc=com",
    "usetls": true,
    "usesearch": false,
    "emailattribute": "mail",
    "id": 2,
    "nameattribute": "uid"
}

To create AD/LDAP Settings, send a POST request to /api/v1/ldapsettings/$DOMAIN_ID/$SERVER_ID.

Retrieve AD/LDAP Settings

Retrieve existing AD/LDAP Settings

curl -v -X GET https://baruwa.example.com/api/v1/ldapsettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Retrieve existing AD/LDAP Settings

{
    "binddn": "uid=readonly-admin,ou=Users,dc=example,dc=com",
    "emailsearchfilter": "",
    "emailsearch_scope": "subtree",
    "searchfilter": "",
    "search_scope": "subtree",
    "authserver": {
        "id": 6
    },
    "basedn": "ou=Users,dc=example,dc=com",
    "usetls": true,
    "usesearch": false,
    "emailattribute": "mail",
    "id": 2,
    "nameattribute": "uid"
}

To retrieve AD/LDAP Settings, send a GET request to /api/v1/ldapsettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID.

Update AD/LDAP Settings

Update AD/LDAP Settings

curl -v -X PUT https://baruwa.example.com/api/v1/ldapsettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "basedn=ou=Users,dc=example,dc=com" \
-d "nameattribute=uid" \
-d "emailattribute=mail" \
-d "binddn=uid=readonly-admin,ou=Users,dc=example,dc=com" \
-d "bindpw=P4ssW0rd###" \
-d "search_scope=subtree" \
-d "emailsearch_scope=subtree"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Update LDAP Settings

{
    "binddn": "uid=readonly-admin,ou=Users,dc=example,dc=com",
    "emailsearchfilter": "",
    "emailsearch_scope": "subtree",
    "searchfilter": "",
    "search_scope": "subtree",
    "authserver": {
        "id": 6
    },
    "basedn": "ou=Users,dc=example,dc=com",
    "usetls": false,
    "usesearch": false,
    "emailattribute": "mail",
    "id": 2,
    "nameattribute": "uid"
}

To update AD/LDAP Settings, send a PUT request to /api/v1/ldapsettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID.

Delete AD/LDAP Settings

Delete AD/LDAP Settings

curl -v -X DELETE https://baruwa.example.com/api/ldapsettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "basedn=ou=Users,dc=example,dc=com" \
-d "nameattribute=uid" \
-d "emailattribute=mail" \
-d "binddn=uid=readonly-admin,ou=Users,dc=example,dc=com" \
-d "bindpw=P4ssW0rd###" \
-d "search_scope=subtree" \
-d "emailsearch_scope=subtree"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To delete AD/LDAP Settings, send a DELETE request to /api/v1/ldapsettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID.

The AD/LDAP Settings will be deleted and the response status will be a 204. This indicates a successful request with no body returned

RADIUS Settings

The RADIUS protocol requires a shared secret between the client and the server, the additional settings allows you to configure this.

Create RADIUS Settings

Create RADIUS Settings

curl -v -X POST https://baruwa.example.com/api/v1/radiussettings/$DOMAIN_ID/$SERVER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "secret=P4ssW0rd#" \
-d "timeout=30"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Create RADIUS Settings

{
    "authserver": {
        "id": 7
    },
    "id": 1,
    "timeout": 30
}

To create RADIUS Settings, send a POST request to /api/v1/radiussettings/$DOMAIN_ID/$SERVER_ID.

Retrieve RADIUS Settings

Retrieve existing RADIUS Settings

curl -v -X GET https://baruwa.example.com/api/v1/radiussettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Retrieve existing RADIUS Settings

{
    "authserver": {
        "id": 7
    },
    "id": 1,
    "timeout": 30
}

To retrieve RADIUS Settings, send a GET request to /api/v1/radiussettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID.

Update RADIUS Settings

Update RADIUS Settings

curl -v -X PUT https://baruwa.example.com/api/v1/radiussettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "secret=P4ssW0rd#" \
-d "timeout=60"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Update RADIUS Settings

{
    "authserver": {
        "id": 7
    },
    "id": 1,
    "timeout": 60
}

To update RADIUS Settings, send a PUT request to /api/v1/radiussettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID.

Delete RADIUS Settings

Delete RADIUS Settings

curl -v -X DELETE https://baruwa.example.com/api/v1/radiussettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "secret=P4ssW0rd#" \
-d "timeout=60"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To delete RADIUS Settings, send a DELETE request to /api/v1/radiussettings/$DOMAIN_ID/$SERVER_ID/$SETTINGS_ID.

The RADIUS Settings will be deleted and the response status will be a 204. This indicates a successful request with no body returned

Organizations

Organizations enable easy management of large number of domains, Administrators are assigned to Organizations and can manage all the domains with in the organization.

You can create smaller organizations out of bigger organizations and add specific domains from a bigger organization to allow delegation of domain management.

The standard organization attributes are:

Attribute Type Description
name String The name of the organization, organizations are used to group domains and assign administrators to manage them
domains Number The domains to add to this organization
admins Number The selected admins will manage all the domains under this organization

Listing all Organizations

List all Organizations

curl -v https://baruwa.example.com/api/v1/organizations \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample response list all organizations

{
    "items": [{
        "domains": [{
            "name": "example.com",
            "id": 2
        }, {
            "name": "example.net",
            "id": 4
        }],
        "name": "TDS",
        "id": 1
    }, {
        "domains": [{
            "name": "example.systems",
            "id": 9
        }],
        "name": "New Technology",
        "id": 2
    }, {
        "domains": [],
        "name": "My Org",
        "id": 3
    }],
    "meta": {
        "total": 3
    }
}

To retrieve a list of all of the organizations on the server, send a GET request to /api/v1/organizations.

The response will be a JSON object with a key called items. The value of this will be an array of Organization objects, each of which contain the standard organization attributes as described above.

Create an Organization

Create an Organization

curl -v -X POST https://baruwa.example.com/api/v1/organizations \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "name=My Org" \
-d "domains=2" \
-d "domains=4" \
-d "admins=3"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample response create an organization

{
    "domains": [{
        "name": "example.com",
        "id": 2
    }, {
        "name": "example.net",
        "id": 4
    }],
    "name": "My Org",
    "id": 4
}

To create a new Organization, send a POST request to /api/v1/organizations.

Set the standard attributes described above.

Retrieve an existing Organization

Retrieve an existing Organization

curl -v https://baruwa.example.com/api/v1/organizations/$ORG_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample response retrieve an existing Organization

{
    "domains": [{
        "name": "example.com",
        "id": 2
    }, {
        "name": "example.net",
        "id": 4
    }],
    "name": "My Org",
    "id": 3
}

To get details about an existing Organization, send a GET request to /api/v1/organizations/$ORG_ID.

The response will be a JSON object that contains the standard attributes defined for an organization as described above.

Update an Organization

Update an Organization

curl -v -X PUT https://baruwa.example.com/api/v1/organizations/$ORG_ID -H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "name=My Org [Updated]" \
-d "domains=2" \
-d "domains=4" \
-d "admins=6"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample response update an Organization

{
    "domains": [{
        "name": "example.com",
        "id": 2
    }, {
        "name": "example.net",
        "id": 4
    }],
    "name": "My Org [Updated]",
    "id": 3
}

To update an Organization, send a PUT request to /api/v1/organizations/$ORG_ID.

Delete an Organization

Delete an Organization

curl -v -X DELETE https://baruwa.example.com/api/v1/organizations/$ORG_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To delete an Organization, send a DELETE request to /api/v1/organizations/$ORG_ID.

The Organization will be deleted and the response status will be a 204. This indicates a successful request with no body returned

Relays

Relaying of outbound mail is authenticated on a per organization basis, to enable an organization to send outbound mail through Baruwa you need to add relay settings.

Two kinds of outbound relaying are supported.

Create Relay settings

Create Relay settings

curl -v -X POST https://baruwa.example.com/api/v1/relays/$ORG_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.20" \
-d "enabled=y" \
-d "require_tls=n" \
-d "username=outboundsmtp" \
-d "password1=Str0ngP4ss##" \
-d "password2=Str0ngP4ss##" \
-d "description=Backup-outbound-smtp" \
-d "low_score=10.0" \
-d "high_score=15.0" \
-d "spam_actions=2" \
-d "highspam_actions=3"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output Create Relay settings

{
    "username": "outboundsmtp",
    "description": "Backup-outbound-smtp",
    "enabled": true,
    "require_tls": false,
    "spam_actions": 2,
    "low_score": 10.0,
    "high_score": 15.0,
    "address": "192.168.1.20",
    "id": 3,
    "highspam_actions": 3
}

To create Relay settings, send a POST request to /api/v1/relays/$ORG_ID.

Retrieve Relay settings

Retrieve Relay settings

curl -v -X GET https://baruwa.example.com/api/v1/relays/$RELAY_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Retrieve Relay settings

{
    "username": "outboundsmtp",
    "description": "Backup-outbound-smtp",
    "enabled": true,
    "require_tls": false,
    "spam_actions": 2,
    "low_score": 10.0,
    "high_score": 15.0,
    "address": "192.168.1.20",
    "id": 3,
    "highspam_actions": 3
}

To retrieve Relay settings, send a GET request to /api/v1/relays/$RELAY_ID.

Update Relay settings

Update Relay settings

curl -v -X PUT https://baruwa.example.com/api/v1/relays/$RELAY_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.20" \
-d "enabled=y" \
-d "require_tls=n" \
-d "username=outboundsmtp" \
-d "description=Backup-outbound-smtp" \
-d "low_score=12.0" \
-d "high_score=20.0" \
-d "spam_actions=2" \
-d "highspam_actions=3"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Update Relay settings

{
    "username": "outboundsmtp",
    "description": "Backup-outbound-smtp",
    "enabled": true,
    "require_tls": false,
    "spam_actions": 2,
    "low_score": 12.0,
    "high_score": 20.0,
    "address": "192.168.1.20",
    "id": 3,
    "highspam_actions": 3
}

To update Relay settings, send a PUT request to /api/v1/relays/$RELAY_ID.

Delete Relay settings

Delete Relay settings

curl -v -X DELETE https://baruwa.example.com/api/v1/relays/$RELAY_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.20"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To delete Relay settings, send a DELETE request to /api/v1/relays/$RELAY_ID.

The Relay settings will be deleted and the response status will be a 204. This indicates a successful request with no body returned

Fallback servers

Fallback servers are used when no delivery server has been configured for a domain. They can be setup in cases where an organization has several domains whose mail is hosted on the same server so it would be repetitive to setup the same delivery server for each domain.

An Organization can have multiple Fallback servers.

Listing Fallback servers

Listing all Fallback servers for an Organization

curl -v -X GET https://baruwa.example.com/api/v1/failbackservers/$ORG_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

orgid = 9

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.get_failbackservers(orgid)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Listing all Fallback servers for an Organization

{
    "items": [{
        "organization": {
            "name": "Baruwa",
            "id": 2
        },
        "protocol": 1,
        "enabled": true,
        "id": 2,
        "address": "192.168.1.150",
        "port": 25
    }],
    "meta": {
        "total": 1
    }
}

To retrieve a list of Fallback servers configured for an Organization, send a GET request to /api/v1/failbackservers/$ORG_ID.

Create a Fallback server

Create a new Fallback server

curl -v -X POST https://baruwa.example.com/api/v1/failbackservers/$ORG_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.151" \
-d "protocol=1" \
-d "port=25" \
-d "require_tls=n" \
-d "enabled=y"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

orgid = 9
data = {
    "address": "192.168.1.152",
    "protocol": "1",
    "port": "25",
    "require_tls": "n",
    "enabled": "y"
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.create_fallbackserver(orgid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Create a new Fallback server

{
    "organization": {
        "name": "Baruwa",
        "id": 2
    },
    "protocol": 1,
    "enabled": true,
    "require_tls": false,
    "id": 9,
    "address": "192.168.1.151",
    "port": 25
}

To create a new Fallback server, send a POST request to /api/v1/failbackservers/$ORG_ID.

Retrieve a Fallback server

Retrieve an existing Fallback server

curl -v -X GET https://baruwa.example.com/api/v1/failbackservers/$SERVER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

orgid = 9
serverid = 4

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.get_fallbackserver(serverid)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output for Retrieve an existing Fallback server

{
    "organization": {
        "name": "Baruwa",
        "id": 2
    },
    "protocol": 1,
    "enabled": true,
    "require_tls": false,
    "id": 9,
    "address": "192.168.1.151",
    "port": 25
}

To retrieve an existing Fallback server, send a GET request to /api/v1/failbackservers/$SERVER_ID.

Update a Fallback server

Update a Fallback server

curl -v -X PUT https://baruwa.example.com/api/v1/failbackservers/$SERVER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.151" \
-d "protocol=1" \
-d "port=25"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

orgid = 9
serverid = 4
data = {
    "address": "192.168.1.153",
    "protocol": "1",
    "port": "25",
    "require_tls": "n",
    "enabled": "y"
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.update_fallbackserver(serverid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output from Update a Fallback server

{
    "organization": {
        "name": "Baruwa",
        "id": 2
    },
    "protocol": 1,
    "enabled": false,
    "require_tls": false,
    "id": 9,
    "address": "192.168.1.151",
    "port": 25
}

To update a Fallback server, send a PUT request to /api/v1/failbackservers/$SERVER_ID.

Delete a Fallback server

Delete a Fallback server

curl -v -X DELETE https://baruwa.example.com/api/v1/failbackservers/$SERVER_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "address=192.168.1.151"
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

serverid = 4
data = {
    "address": "192.168.1.153",
}

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
api.delete_fallbackserver(serverid, data)
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

To delete a Fallback server, send a DELETE request to /api/v1/failbackservers/$SERVER_ID.

The Fallback server will be deleted and the response status will be a 204. This indicates a successful request with no body returned

System Status

System status gives you a dash board view of your Baruwa system or cluster.

The following information is provided:

Retrieve System Status

Retrieve System Status

curl -v -X GET https://baruwa.example.com/api/v1/status \
-H "Accept: application/json" \
-H "Authorization: Bearer $TOKEN" \
require 'baruwa'

api = BaruwaAPI.new('token', 'https://baruwa.example.com')
from BaruwaAPI import BaruwaAPIClient

api = BaruwaAPIClient('token', 'https://baruwa.example.com')
use Net::BaruwaAPI;

my $api = Net::BaruwaAPI->new(
    api_token => 'token',
    api_url => 'https://baruwa.example.com'
);

Sample output from Retrieve System Status

{
    "inbound": 0,
    "status": true,
    "total": [19, 19, 0, 0, 0, 0, 0],
    "outbound": 0
}

To retrieve System Status, send a GET request to /api/v1/status.