Sending requests

All requests are made by sending an HTTP POST request to the URI for an
API method, for example, https://api.hostedemail.com/method.

The base URI for the OMA differs, depending on the OpenSRS email
environment:

• Production Test—https://admin.test.hostedemail.com/api
• Cluster A—https://admin.a.hostedemail.com/api
• Cluster B—https://admin.b.hostedemail.com/api

The rest of the URI is the method name. For example, to call the get_user
method on Cluster A, you would send the following HTTP POST request:
https://admin.a.hostedemail.com/api/get_user.

Request format

Each OMA request consists of a single JSON object. That object must have a
credentials object, which contains a user string and either a password or a
session_token. The password is the user's password. Alternatively a session_token is a limited-lifetime token that can be generated by using the authenticate or the generate_token method.

📘

Note:

In the examples provided in this guide, the name that you see in the user field indicates the minimum permission level required to submit the method, for example, [email protected] or [email protected].

The credentials object may contain a client key with a string value. This value is used for internal logging.

The request may also contain other key-value pairs, depending on the method being called.

"credentials":{
	"user": "<user name>", 
  "password": "<user password>", 
  "token": "<session token>", 
  "client": "<client id string>"
}

Example request

{
    "credentials":{
			"user": "[email protected]", 
      "password": "sw0rdf1sh",
			"client": "My OMA Client v1.0"
    }
		Some_valid_method_request_field
}

Response format

All responses consist of a single JSON object that contains a success boolean value. If the value is false, the response object also contains an error number and text to help you determine what caused the error. Regardless of the value of success, the response may also contain some additional data. For requests that query or change multiple objects, the response may contain success and error fields for each object.

Example error response

{
	"success": false,
	"error_number": 1,
	"error": "Invalid credentials supplied in request"
}

Example success response

{
    "success": true,
    "............