api.mailbox.org : The basics

API URL and character set

All requests will be sent via POST to the following URL: 

https://api.mailbox.org/v1/

The application uses the UTF-8 character set.

JSON-RPC 2.0

Requests and API responses are compliant with the JSON-RPC 2.0 specification.

Authentication

It is possible to send anonymous as well as authenticated requests through the API.
An authenticated request contains an HTTP header with a valid Auth-ID. 

How to get an Auth-ID

When calling the auth method with a valid username and password as parameters, an Auth-ID will be returned in response.
This ID is then used as a PHP session ID, valid for an initial 20 minutes. Validity duration is topped up to 20 minutes every time there is user activity on the site.

Part of the response is also the so-called auth level. Some API methods require a minimum auth level to work.
The following levels are defined: admin, reseller, account, domain, mail, ftp 

Send Auth-ID with HTTP header 

The API client sends the ID with the HTTP header HPLS-AUTH.

HPLS-AUTH: dlj3keZzTupJyX;KsSv57037ba615c926.43918213

Once an Auth-ID is no longer valid, the following error will be returned:

{
  "jsonrpc":"2.0",
  "error":{
    "code":253,
    "message":"This Auth-ID is invalid"
  },
  "id":"1"
}

Using an API client simplifies the handling of the Auth-ID.

API client

For better usability we are providing a PHP API client.
The latest version of the client code is available for download at the following URL:

https://api.mailbox.org/v1/client

A comprehensive documentation of the PHP API client is available in English and German for further reference.

We are working to support additional languages in the future.

Context-ID

A context comprises the users, groups, and resources (e.g., meeting rooms) with their related objects. Any data from calendars or file folders can be easily shared between users that also share the same context, in that the information can be embedded directly in their web interfaces. Sharing the information with users that are not in the same context can be achieved by generating a link which can then be opened by external users in a separate browser tab or window.

It is possible to maintain several different domains within the same context, so that the e-mail accounts defined for these domains can benefit from shared calendars and address books. 

Error reporting

The API will report any errors with an error code attached, however currently, this code may be somewhat unspecific if there are parameters missing from the request.
If this happens, we can at this point only suggest double-checking the implementation with the help of our documentation files.

We are working on a solution that will transmit details of any errors that may have ocurred in the "data" part of the error object.

Adding domains

When adding domains, the API will check if the DNS record of the domain contains the mailbox.org security key. If this is the case, then the domain will be added and usable in an instant.
The security key is generated by mailbox.org and must be present in the TXT record of a subdomain that belongs to the domain to be added.

If this DNS security key is missing, then the method domain.add will return an error 218. This is not uncommon if a user tries to add an existing domain for the first time:

{
  "jsonrpc":"2.0",
  "error":{
    "code":218,
    "message":"The DNS TXT record does not contain the correct data",
    "data":{
      "host":"5adc6e5a00bfa3f9fe1b1e14c73e03ad651b601c.domain.test",
      "txt":"9dd07dc055aee1b63eb55f3e2874d5f253b3f643"
    }
  },
  "id":"1"
}


In the example above, the host value that is part of the data object is for a new subdomain and the value of txt is the data for the TXT record of that subdomain. Only if this security key has been set in the DNS will a user be able to add the domain.

In the example,

  1. The subdomain 5adc6e5a00bfa3f9fe1b1e14c73e03ad651b601c.domain.test needs to be created and
  2. its TXT record must be set to 9dd07dc055aee1b63eb55f3e2874d5f253b3f643

Please note: Due to the way DNS information is updated across the Internet, it can take several hours for the new security key to be accessible to our systems.