{"_id":"56abe05f678b58170031ec46","category":{"_id":"56abdd81d4432d1900eed235","__v":6,"version":"569f9cf6650e1d1900f96b5e","pages":["56abddd30b9e0b0d006162b1","56abde024e4b730d009eb11a","56abe05f678b58170031ec46","56ad2053d21f1b0d00fd2f82","56ad2a922a7860170013f70d","56ad2b663fc1020d009776da"],"project":"569f9cf6650e1d1900f96b5b","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-29T21:45:37.383Z","from_sync":false,"order":2,"slug":"introduction","title":"Introduction"},"user":"5582e90181672a3900bb4fc7","project":"569f9cf6650e1d1900f96b5b","__v":25,"githubsync":"","version":{"_id":"569f9cf6650e1d1900f96b5e","project":"569f9cf6650e1d1900f96b5b","__v":12,"createdAt":"2016-01-20T14:43:02.785Z","releaseDate":"2016-01-20T14:43:02.785Z","categories":["569f9cf7650e1d1900f96b5f","56abdd81d4432d1900eed235","56abe0558beeff0d003b8118","56ad2f8b1c09150d00a183a8","56ad4e1cd21f1b0d00fd2f97","56b00ad88f7a4f0d0029dc92","56b2432e9621f20d00efb2bd","56b25826147e900d00d6497a","56b7af2a4b372d2100722c48","56b8c4d938b1070d0028920f","56b8cdab14feef0d0082415d","58599813cf9e112d0032cdab"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-29T21:57:51.930Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"All requests are made by sending an HTTP POST request to the URI for an\nAPI method, for example, https://api.hostedemail.com/method.\n\nThe base URI for the OMA differs, depending on the OpenSRS email\nenvironment:\n\n  * **􀂃 Production Test**—[https://admin.test.hostedemail.com/api](https://admin.test.hostedemail.com/api) ADD LINK\n  * 􀂃** Cluster A**—[https://admin.a.hostedemail.com/api](https://admin.a.hostedemail.com/api) ADD LINK\n  * 􀂃 **Cluster B**—[https://admin.b.hosedemail.com/api ](http://google.com) ADD LINK \n\nThe rest of the URI is the method name. For example, to call the get_user\nmethod on Cluster A, you would send the following HTTP POST request:\n[https://admin.a.hostedemail.com/api/get_user](https://admin.a.hostedemail.com/api/get_user). ADD LINK\n\n## Request format\n\nEach OMA request consists of a single JSON object. That object must have a\n**credentials** object, which contains a user string and either a **password** or a\n**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](https://api-opensrs-email.readme.io/v1.0/docs/authenticate?bypass=8272e34bb5) or the generate_token method.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"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, domain_admin:::at:::example.com or company_admin@example.com.\",\n  \"title\": \"Note:\"\n}\n[/block]\nThe **credentials** object may contain a **client** key with a string value. This value is used for internal logging.\n\nThe request may also contain other key-value pairs, depending on the method being called.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"credentials\\\":{\\n\\t\\\"user\\\": \\\"<user name>\\\", \\n  \\\"password\\\": \\\"<user password>\\\", \\n  \\\"token\\\": \\\"<session token>\\\", \\n  \\\"client\\\": \\\"<client id string>\\\"\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Example request \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"credentials\\\":{\\n\\t\\t\\t\\\"user\\\": \\\"domain_admin@example.com\\\", \\n      \\\"password\\\": \\\"sw0rdf1sh\\\",\\n\\t\\t\\t\\\"client\\\": \\\"My OMA Client v1.0\\\"\\n    }\\n\\t\\tSome_valid_method_request_field\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Response format \n\nAll 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.\n\n**Example error response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"success\\\": false,\\n\\t\\\"error_number\\\": 1,\\n\\t\\\"error\\\": \\\"Invalid credentials supplied in request\\\"\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Example success response \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"success\\\": true,\\n    \\\"............\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"sending-requests","type":"basic","title":"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](https://admin.test.hostedemail.com/api) ADD LINK * 􀂃** Cluster A**—[https://admin.a.hostedemail.com/api](https://admin.a.hostedemail.com/api) ADD LINK * 􀂃 **Cluster B**—[https://admin.b.hosedemail.com/api ](http://google.com) ADD LINK 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](https://admin.a.hostedemail.com/api/get_user). ADD LINK ## 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](https://api-opensrs-email.readme.io/v1.0/docs/authenticate?bypass=8272e34bb5) or the generate_token method. [block:callout] { "type": "info", "body": "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, domain_admin@example.com or company_admin@example.com.", "title": "Note:" } [/block] 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. [block:code] { "codes": [ { "code": "\"credentials\":{\n\t\"user\": \"<user name>\", \n \"password\": \"<user password>\", \n \"token\": \"<session token>\", \n \"client\": \"<client id string>\"\n}", "language": "perl", "name": " " } ] } [/block] ## Example request [block:code] { "codes": [ { "code": "{\n \"credentials\":{\n\t\t\t\"user\": \"domain_admin@example.com\", \n \"password\": \"sw0rdf1sh\",\n\t\t\t\"client\": \"My OMA Client v1.0\"\n }\n\t\tSome_valid_method_request_field\n}", "language": "perl", "name": " " } ] } [/block] ## 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** [block:code] { "codes": [ { "code": "{\n\t\"success\": false,\n\t\"error_number\": 1,\n\t\"error\": \"Invalid credentials supplied in request\"\n}", "language": "perl", "name": " " } ] } [/block] ## Example success response [block:code] { "codes": [ { "code": "{\n \"success\": true,\n \"............", "language": "perl", "name": " " } ] } [/block]