Roller Network Account Manager API Help
Please note: the Account Manager API is provided for advanced users only.
The Roller Network Account Manager API allows our services and systems to be integrated into an existing system or infrastructure. Security is through an "access key" which can limit access to areas of the account manager by permissions settings and source IP address without revealing your account login. Before using the API a key must be configured to allow access.
By using a system of keys and (optional) IP address restrictions, the API can be used to integrate the account manager into an existing system. This is currently performed by executing HTTP/HTTPS calls to the API in a GET or POST method.
Perl Module Interface
Sections
Configuring the API
Before the API can be used, a key and optional IP address must be added through the account manager. The API key can be any combination of characters up to 128 characters long. If the IP address limit field is left blank, the account manager will allow any IP address utilizing the key. If an IP address (or IP range in CIDR slash-mask format) is given, only requests from that IP address will be authorized.
After a key has been added it will appear in the "Current API Keys" list. By default, the newly added key will not have any permission to make changes. To update and enable permission, change any "Deny" modes to "Allow" modes, and update the settings. Once this is done, the API key is ready to be used.
Once added, the key and IP address can not be changed. The key must be deleted and a new key added in order to change these values.
API Overview
The API may be accessed by making a HTTP or HTTPS request, in GET or POST mode, to the address http://acc.rollernet.us/api/api.php and passing it the following variables:
| Variable | Description | |
| u | The account manager user name. | |
| k | An API access key. | |
| m | API module or mode to access. | |
| a | An action to perform. | |
| d | Data required to perform the action. |
The API will only return two values when a request is made: OK or ERROR. No details on error will be provided through the API; they are available in the API log available through the account manager. This is an example of a request using HTTPS and GET:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=rmap&a=add&d=user@mydomain.com
Each of the required variables has the following value:
| Variable | Value | |
| u | myuser | |
| k | mykey | |
| m | rmap | |
| a | add | |
| d | user@mydomain.com |
This would request the API to change the Recipient Maps mode for the domain "mydomain.com" to "Enabled" for the account "myuser" using the authorization key "mykey". If this action was successful, the API would return OK. If the action failed for any reason, the API would return ERROR. All API activity is logged in the account manager.
Depending on the platform used to send the API requests, the non-alphanumeric characters in variable values may require encoding. The encoded version of the same example above is:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=rmap&a=add&d=user%40mydomain.com
Valid User Table "rmap" Method
The "rmap" method provides an interface to the valid user table feature. This fucntion was also called "Recipient Maps" in the past. It allows a valid user entry to be added or removed and for the domain mode to be changed. The following actions are provided to the rmap module:
| Action | Description | |
| add | Adds an email address. | |
| del | Removes an email address. | |
| deny | Changes domain policy to "Default Deny". | |
| allow | Changes domain policy to "Default Allow". | |
| defer | Changes domain policy to "Defer Incoming". | |
| global | Changes domain to use the global valid user table. | |
| table | Return the current valid user table. | |
| mode | Return the default action mode for a domain. |
For the add and del actions, the data variable d is a valid email address in user@domain.com format. All other actions require the data variable d to be a valid domain name.
The mode action will return OK followed by a new line with the mail domain name and a mode=x value where x will be one of: hosted (a hosted mail domain), allow (default allow policy), deny (default deny policy), defer (defer incoming policy), auto (automatic learning mode), global (use global valid user table policy).
Examples using HTTPS and GET:
Adding an entry to the valid user table:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=rmap&a=add&d=user@mydomain.com
Returns OK if successful. This action will also return ERROR if the entry is a duplicate or d is not a valid email address.
Removing an entry to the valid user table:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=rmap&a=del&d=user@mydomain.com
Always returns OK, even if the entry does not exist, unless d is not a valid email address.
Changing the default policy:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=rmap&a=allow&d=mydomain.com
Returns OK unless d is not a valid domain name.
Mail Domains "maildomain" Method
The "maildomain" method allows the API to add, delete, enable, and disable mail domains. The following actions are provided to the maildomain module:
| Action | Description | |
| add | Adds a new domain and sets it to "Secondary MX" mode. | |
| delete | Removes a domain. | |
| mx | Set an existing domain to "Secondary MX" mode. | |
| redirect | Set an existing domain to "SMTP Redirection" mode. (Extended data format; see below.) | |
| hold | Set an existing domain to "Accept and Hold Messages" mode. | |
| enable | Enables a mail domain. | |
| disable | Disables a mail domain. | |
| slowenable | Enables "slow delivery" mode. | |
| slowdisable | Disables "slow delivery" mode. |
For all actions, the value of d passed to the API must be a valid domain name. If it is not, ERROR will be returned.
Extended data format:
The SMTP Redirection action requries a host and port, in addition to the domain name. This is passed to the API by setting the data d value to "domain.com|destination.host.com:port". Example:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=maildomain&a=redirect&d=mydomain.com|mail.myserver.com:2525
Examples using HTTPS and GET:
Adding a new domain name:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=maildomain&a=add&d=mydomain.com
Returns OK if successful. This action will return ERROR if the entry is a duplicate or already exists in another account.
Removing a domain name:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=maildomain&a=del&d=mydomain.com
Returns OK if domain exists and was successfully removed. Returns ERROR if the domain is invalid, does not exist, or is not associated with this account.
Disabling a domain name:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=maildomain&a=disable&d=mydomain.com
Returns OK if domain was disabled, regardless of previous state. Returns ERROR if the domain is invalid, does not exist, or is not associated with this account.
Enabling a domain name:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=maildomain&a=enable&d=mydomain.com
Returns OK if domain was enabled, regardless of previous state. Returns ERROR if the domain is invalid, does not exist, or is not associated with this account.
The "secdns" method allows the API to add, delete, enable, and disable secondary DNS domains. The following actions are provided to the secdns module:
| Action | Description | |
| add | Adds a domain with specified master. | |
| delete | Removes a secondary DNS domain. | |
| enable | Enables a secondary DNS domain. | |
| disable | Disables a secondary DNS domain. | |
| retransfer | Request a retransfer on all DNS servers. | |
| delzone | Delete zone file from all DNS servers. | |
| list | Returns a list of zones in the format: zone,status,master |
For all actions, the value of d passed to the API must be a valid domain name. If it is not, ERROR will be returned.
Important: Since a master needs to be specified when adding Secondary DNS domains, the data d variable requires an additional parameter. Multiple parameters are separated by the pipe character "|". To use the add action, speficy d as "domain|master". This format may be used with other actions; the master portion will be ignored.
Examples using HTTPS and GET:
Adding a new domain name:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=secdns&a=add&d=mydomain.com|master.mydomain.com
Returns OK if successful. This action will return ERROR if the entry is a duplicate, bad master format, or already exists in another account.
Removing a domain name:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=secdns&a=del&d=mydomain.com
Returns OK if domain exists and was successfully removed. Returns ERROR if the domain is invalid, does not exist, or is not associated with this account.
Listing all Secondary DNS zones:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=secdns&a=list&d= example.net,1,198.51.100.4 example.org,0,192.0.2.1 example.com,1,2001:db8::a:3 OK
Returns a list of secondary DNS zones in the format zone,status,master terminated with OK. The domain d input is required, but is ignored and may be left blank. Status is 0 (zero) for disabled and 1 (one) for enabled.
The "mailqueue" method lets you retrieve information on a queue and execute an ETRN. Its functionality is identical to the mail queue status page. The following actions are provided to the mailqueue module:
| Action | Description | |
| status | Returns the queue status of one or more mail domains. | |
| etrn | Executes an ETRN for a specific mail domain. |
For the status action, the value of d passed to the API should be a mail domain name or empty string. If it is an empty string or contains an invalid mail domain, the queue status of all domains is returned. If a valid domain name is given for the value of d only the status of that domain will be returned.
The format of the queue status is one line per mail domain as follows:
<mail domain name>,<mail.rollernet.us count>,<mail2.rollernet.us count>
Example:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=mailqueue&a=status&d= OK example.com,0,0 example.net,0,0 example.org,0,0
Single domain example:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=mailqueue&a=status&d=example.com OK example.com,0,0
For the etrn action the value of d must be a valid mail domain. If it is not, ERROR will be returned. ERROR may also be returned if the etrn action failed, otherwise OK will be returned.
Example using the etrn action:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=mailqueue&a=etrn&d=example.com
Hosted Mail Box "mailbox" Method
The "mailbox" method lets you perform actions on hosted mail boxes. The following actions are provided to the mailbox module:
| Action | Description | |
| add | Create a new hosted mail box account. | |
| vpasswd | Changes password with old password verification. | |
| passwd | Changes the password without verification. | |
| remove | Removes a hosted mail box account. |
This method requires multiple data d inputs in an array form depending on the action. They are:
| Data | Description | |
| d[u] | The hosted mail box account, or user name. | |
| d[p] | The (new) account password. | |
| d[vp] | The old account password (for vpasswd). | |
| d[o] | Matching outbound account (for add and remove). Value is 0 (no) or 1 (yes). |
| Action | Required Data Inputs | |
| add | d[u] d[p] d[o] | |
| vpasswd | d[u] d[p] d[vp] | |
| passwd | d[u] d[p] | |
| remove | d[u] d[o] |
Both passwd and vpasswd will use the value supplied in d[p] as the new password for the mail box account named in the d[u] value. If the mail box does not exist ERROR will be returned. OK will be returned if the password was successfully changed.
The only difference between passwd and vpasswd is that vpasswd requires the current password to be provided in the d[vp] input; ERROR will be returned if it does not match the current password. This allows the API to be used to build a customer-facing password change form whereas passwd should only be used as a trusted administrative function.
When using the add method you can create regular user accounts by passing d[u] with value mailbox@example.com or any user (dropbox, catchall) accounts with value @example.com .
Example
Example using the add action with HTTPS GET:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=mailbox&a=add&d[u]=mailbox@example.com&d[p]=pass&d[o]=1
Example using the vpasswd action with HTTPS GET:
https://acc.rollernet.us/api/api.php?u=myuser&k=mykey&m=mailbox&a=vpasswd&d[u]=mailbox@example.com&d[p]=newpass&d[vp]=oldpass