Rackspace Email & Apps API - User contributions [en]

Main Page

2020-12-02T23:21:29Z

Matt.Brown: Fix copy/pasted URL

== Introduction ==

The Rackspace Email Rest API provides most of the functions of the Control Panel through a REST-based [http://en.wikipedia.org/wiki/Web_service web API]. Whether it is adding a new customer account, adding mailboxes, or any other of the supported features the API allows your application to administer the changes regardless of your application's language or nature. For more information on RESTful web services refer to the following sites:

[http://www.peej.co.uk/articles/restfully-delicious.html Paul James's Homepage: A RESTful Web service, an example]

[http://en.wikipedia.org/wiki/Representational_State_Transfer#External_links Wikipedia: Representational State Transfer - External Links]

The API is accessible to all with access to Control Panel, including resellers, business customers, enterprise customers, and indirect customers. However, not all operations are available to non-resellers. See the [[Rest_API#Operations|Operations]] section for more details.

The Rackspace Email Soap API Homepage has been moved to [[Soap_API| here]].

== Operations ==

The following pages detail the operations that the API supports. The operations are grouped into sections based on the entity/object types that each operation interacts with. Non-resellers do not have access to all functions.

{| class="wikitable"
!Resource
!Example URI
!Business User Access
|-
| [[Customer_(Rest_API)| Customer]]
| /customers/123456789
| [[Customer_(Rest_API)#Create_Login_Tokens | Create Login Tokens]]
|-
| [[Admin_(Rest_API)| Admin]]
| /customers/123456789/admins/my_admin
| All
|-
| [[Domain_(Rest_API)| Domain]]
| /customers/123456789/domains/example.com
| [[Domain_(Rest_API)#Index| Index]], [[Domain_(Rest_API)#Show| Show]], [[Domain_(Rest_API)#Split Domain Routing| Split Domain Routing]], [[Domain_(Rest_API)#Archiving SSO Login URL| Archiving SSO Login URL]], [[Domain_(Rest_API)#Domain_Public_Folders_.28Reseller_Only.29|Domain Public Folders]], [[Domain_(Rest_API)#Domain Email Everyone| Email Everyone ]], [[Domain_(Rest_API)#Show_Domain_Catch-All_Address | Catch-All Address]]
|-
| [[Domain_Spam_(Rest_API)| Domain Spam Settings]]
| /customers/123456789/domains/example.com/spam/settings
| All
|-
| [[Domain_Webmail_Settings_(Rest_API)| Domain Webmail Settings]]
| /customers/123456789/domains/example.com/webmailSettings
| All
|-
| [[Rackspace_Mailbox_(Rest_API)| Rackspace Email Mailbox]]
| /customers/123456789/domains/example.com/rs/mailboxes/john.smith
| All
|-
| [[Rackspace_Mailbox_Spam_(Rest_API)| Rackspace Email Mailbox Spam Settings]]
| /customers/123456789/domains/example.com/rs/mailboxes/john.smith/spam
| All
|-
| [[Rackspace_Storage_Notification_(Rest_API)| Rackspace Storage Notification Settings]]
| /customers/123456789/domains/example.com/rs/storageNotification
| All
|-
| [[Rackspace_Alias(Rest_API)| Rackspace Email Alias]]
| /customers/123456789/domains/example.com/rs/mailboxes/john.smith/alias
| All
|-
| [[Exchange_Mailbox_(Rest_API)| Exchange Mailbox]]
| /customers/123456789/domains/example.com/ex/mailboxes/john.smith
| All
|-
| [[Exchange_Mailbox_Spam_(Rest_API)| Exchange Mailbox Spam Settings]]
| /customers/123456789/domains/example.com/ex/mailboxes/john.smith/spam
| All
|-
| [[Exchange_Contact_(Rest_API)| Exchange Contact]]
| /customers/123456789/domains/example.com/ex/contacts/john.smith
| All
|-
| [[Exchange_Distribution_List_(Rest_API)| Exchange Distribution List]]
| /customers/123456789/domains/example.com/ex/distributionlists/group.name
| All
|-
| [[Exchange_Resource_Mailbox_(Rest_API)| Exchange Resource Mailbox]]
| /customers/123456789/domains/example.com/ex/resources/conference.room
| All
|-
| [[Exchange_Skype_For_Business_(Rest_API)| Exchange Skype For Business]]
| /customers/123456789/domains/example.com/ex/lync/users
| All
|-
| [[Exchange_Public_Folders_(Rest_API)| Exchange Public Folders]]
| /customers/123456789/domains/example.com/ex/publicFolders
| All
|-
| [[SharePoint_(Rest_API)| SharePoint]]
| /customers/123456789/sharepoint/settings
| [[SharePoint_(Rest_API)#Show | Show]]
|}

The examples shown in the operation pages are written in Ruby and extensively use the helper functions shown in the Ruby Examples below.

== Quick Start ==

'''What you need:'''
* A Rackspace Email and Apps Control Panel admin account
* A HTTP class library that supports TLS 1.2 or greater, and the HTTP methods: GET, POST, PUT, DELETE.

'''Making your first API call, an Show Customer request:'''
# Obtain your API keys
#:* Login to [https://cp.rackspace.com Control Panel]
#:* Click the drop down in the top right next to your admin id/account number.
#:* Click Admins & Contacts
#:* Click API Keys
# Set up your client's HTTP request
#:* Set up your client to make calls to a URL beginning with <nowiki>https://api.emailsrvr.com/v1</nowiki>.
#:* Populate the Accept, User-Agent and X-Api-Signature HTTP request headers correctly. This is explained in detail [[#HTTP Headers|here]].
# Make a GET request to /customers/me.
#:* The complete URI will be <nowiki>https://api.emailsrvr.com/v1/customers/me/domains</nowiki>. Use your HTTP library to retrieve the HTTP response code, 'x-error-message' HTTP response header and HTTP response body so that they may be displayed to help debug and determine success.
'''From here:'''
* Learn about the operations you'll be implementing at the subpages [[#Operations|here]].

== Accessing the API ==

Your application should need to make HTTP requests over TLS 1.2 or greater (HTTPS) to our API servers. Most programming languages have this functionality built into their core libraries. In addition to the common GET and POST HTTP methods, the library used will also need to support PUT and DELETE.

For some language's libraries, simply using an URL that starts with https:// will cause the library to use TLS. In some other libraries however some options specific to the library may have to be configured to utilize TLS.

All API calls should be directed to a URL in the following format:
<pre>https://api.emailsrvr.com/(version)/(resource)</pre>

Example:
<pre>https://api.emailsrvr.com/v1/customers/12345678/domains/customerbusiness.com</pre>

=== Versions ===

{| class="wikitable"
!''Supported Versions''
!''URL''
!''Version Documentation''
|-
| v1 (current)
| <nowiki>https://api.emailsrvr.com/v1/</nowiki>
| http://api-wiki.apps.rackspace.com/api-wiki/index.php/Main_Page
|}

The API version number is a component of the URL that is used to access the API. For example, to access the root of the API, the URL is https://api.emailsrvr.com/v1/. Bug fixes and minor non-breaking changes will be made without changing the version number. When major features or breaking changes are introduced, the version number will be incremented. It is not yet determined how many versions are going to be supported at any one time.

'''Using the discontinued v0 API?'''

* If your client consumes v0 of the Admin REST API for Exchange Distribution Lists or Exchange Resource Mailboxes routes, the client must be updated to consume the new behavior in v1.
* If your client does not consume the v0 Admin REST API for Exchange Distribution Lists and Exchange Resource Mailboxes, you simply need to update the base URL (i.e. https://api.emailsrvr.com/v0/…) from v0 to v1. There were no changes to the behavior of the other entities in the API, only their location changed.

{| class="wikitable"
!''Non-breaking Changes''
!''Breaking Changes''
|-
| Adding new fields or attributes to form fields sent
| Changing or deleting any fields in form fields sent
|-
| Adding fields in returned data
| Changing or removing fields in returned data
|-
|
| Changing the URI of any resource
|}

=== Authentication ===

To gain access to the API, your request must include a properly constructed X-Api-Signature HTTP header. Details on what to put in the header are below. To construct the header, you must have the following keys that are generated from the [https://cp.rackspace.com/MyAccount/Administrators/ApiKeys API Keys] page.

{| class="wikitable"
!Key Name
!Description
!Example
|-
| User Key
| A public key that corresponds to your admin id
| ''eGbq9/2hcZsRlr1JV1Pi''
|-
| Secret Key
| A shared secret key
| ''QHOvchm/40czXhJ1OxfxK7jDHr3t''
|}

An unsuccessful authentication will result in a 403 HTTP code.

==== X-Api-Signature Header ====

Format is as follows:
<'''User Key'''>:<'''Timestamp'''>:<'''SHA1 Hash'''> 
Example: ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:46VIwd66mOFGG8IkbgnLlXnfnkU=''

Remember to include the colons between the data strings!

 
'''User Key''': 
This is the public key issued by the Control Panel browser interface.

 
'''Timestamp''': 
The format is YYYYMMDDHHmmss. All values besides year are zero-padded to two spaces. For example, March 08th 2001 at 2:37.25pm would be ''20010308143725''.

{| class="wikitable"
|YYYY
|Four-digit year
|-
| MM
| Month
|-
| DD
| Day
|-
| HH
| Hour in 24h format
|-
| mm
| Minute
|-
| ss
| Second
|}

'''SHA1 Hash''':

A SHA1 (Secure Hash Algorithm) hash must be applied to a string with the following information:

<'''User Key'''><'''User Agent'''><'''Timestamp'''><'''Secret Key'''>

Note that the 'User Agent' must be the exact same as what is specified in the User-Agent HTTP header. Using the above example data, the string before hashing is: ''eGbq9/2hcZsRlr1JV1PiRackspace Management Interface20010308143725QHOvchm/40czXhJ1OxfxK7jDHr3t''

Resulting base-64 SHA1 Hash: ''46VIwd66mOFGG8IkbgnLlXnfnkU=''

Be sure to encode the binary hash, not the hex hash, into base-64. The resulting string should be 28 characters long.

== Using the API ==

=== Requests ===

HTTP requests should be sent to the server with the correct URL, HTTP method, HTTP headers and form data (if needed). The URL specifies the resource, the HTTP method specifies what operation is done on the resource, and form data is used to specify the details of the resource when the resource is added or edited.

The URLs, corresponding HTTP methods, and necessary form data for the desired operations are detailed in the [[#Operations|operation pages]].

If you're getting the HTTP status code 417 see [[Handling HTTP code 417: Expectation failed]]

==== URL ====

The URLs are specifies the resource or resource collection. Objects are organized in a tree collection, starting with customers at the top, then domains, then domain objects next (such as mailboxes, contacts, and distribution lists) and so on. The URLs of the resources and collections accessible are found on the operation pages.

==== HTTP Method ====

It is the HTTP method that specifies what operation will be done on the resource. For example, to get the details of a mailbox a HTTP GET will be done on /customers/12345678/domains/example.com/ex/mailboxes/john.smith. If the mailbox does not exist, a HTTP POST to the same URL with the necessary form data will add the mailbox. Then, a HTTP PUT to the same URL will edit mailbox. And to delete the mailbox, an HTTP DELETE would be used.

The types of operations a certain method performs is outlined below.

{| class="wikitable"
!''HTTP Method''
!''Operations''
!''Response''
|-
|rowspan=2|GET
|Index - returns a list of the resources
|rowspan=2|XML or JSON formatted data
|-
|Show - returns the details of the resource
|-
|POST
|Add - adds a new resource
|rowspan=3|Response code and error message (if applicable) only
|-
|PUT
|Edit - changes the details of the resource
|-
|DELETE
|Delete - deletes the resource
|}

==== HTTP Headers ====

All requests to the API must then include HTTP headers with the following information:

{| class="wikitable"
!''Header Name''
!''Description''
!''Example Header Value''
|-
| Accept
| The requested content type (required for Index and Show actions). Fill this with either 'text/xml' or 'application/json'. See [[#Formats|Response Formats]]
| ''text/xml''
|-
| User-Agent
| An identifier you choose for your client software
| ''Rackspace Management Interface''
|-
| X-Api-Signature
| An authentication string explained in detail [[#X-Api-Signature_Header|here]]
| ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''
|}

==== Form Data ====

When using Add and Edit operations, the details of the resource are sent to the API server via HTTP form data. Your HTTP library should include methods for sending form data along with an HTTP request. The library should by default send the data in the HTTP request body using the 'application/x-www-form-urlencoded' data format.

==== Index Filter/Search ====

The results of Index actions can be filtered/searched. The index URLs can take either one of the query strings: "?startswith=xx" or "?contains=xx," where "xx" is the key word. If the request specifies more than one of these two query strings, a 400 HTTP error will be returned. Different fields will be searched depending on the resource type, see below.

Note that "0-9" is a reserved key word for query string "startswith." It represents any result starting with numbers.

{| class="wikitable"
!''Index Actions''
!''Where the key word will be searched''
|-
| Customer
| Customer name, account number, reference number
|-
| Domain
| Domain name
|-
| Mailbox
| Mailbox name, mailbox display name, custom ID field
|-
| Contact
| Contact display name, external email
|-
| Group
| Group name, group display name
|-
| Mobile Service
| Associated mailbox name, mailbox display name
|-
| Lync Users
| Mailbox name (NOTE: Does not support the startsWith search parameter)
|}

==== Throttling ====

The server limits the number of requests allowed per user in a certain period of time. The number of requests made are logged per minute. Calls that were made correctly with a user's API key, but not completed for any reason, including those exceeding the throttle limit, are included in this count.

If a user is over the throttling limit then a 403 HTTP code will be returned with an "Exceeded request limits" message.

{| class="wikitable"
!''Operation Category''
!''Request Limit''
|-
| GET
| 120 per minute
|-
| PUT, POST, DELETE
| 90 per minute
|-
| POST, PUT, DELETE on a domain
| 2 per minute
|-
| POST, DELETE on alternate domains
| 2 per minute
|-
| Enabling public folders for a domain
| 1 per 5 minutes
|}

==== Examples ====

Index of Exchange Mailboxes:
<pre>
Hypertext Transfer Protocol
GET /v1/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100 HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml
</pre>

Adding New Exchange Mailbox:
<pre>
Hypertext Transfer Protocol
POST /v1/customers/12345678/domains/example.com/ex/mailboxes/john.smith HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Content-Length: 53
[Content length: 53]
Content-Type: application/x-www-form-urlencoded

Line-based text data: application/x-www-form-urlencoded
size=2048&displayName=John%20Smith&password=abcABC123

</pre>

=== Responses ===

==== HTTP Status Code ====

On a successfully executed request, a 200 HTTP Code is returned. If the request was unsuccessful however, an HTTP error code in the 400s or 500s will be returned.

==== HTTP Response Body ====

If the request is an Index or Show request, the request data will be returned in the format specified in the HTTP Body.

===== Formats =====

Requests for data (index and show requests) are returned with XML or JSON data based on what your application populates the [[#HTTP_Headers|HTTP Accept headers]] with.

For XML, populate the header with 'text/xml' (ex: Headers!["Accept"] = "text/xml"). The XML document returned will conform to a published XSD (XML Schema Document). There are many ways to parse the data in an XML document, but we have found that the [http://www.w3schools.com/XPath/default.asp XPath] tree-style traversal has served our purposes. In any case, your application will likely need to use a class library for your chosen method.

For JSON, populate the header with 'application/json' (ex: Headers!["Accept"] = "application/json"). As with XML, a library will likely be needed to parse the data.

==== HTTP Headers ====

The only data returned in the header is the error message (if any).

{| class="wikitable"
!''Header Name''
!''Description''
!''Example Header Value''
|-
| x-error-message
| The error message. See [[#Errors|Errors]].
| Missing required field: name
|}

==== Errors ====

See [[Errors]].

==== Paging ====

The results of Index actions are split into pages to lessen potentially high resource usage. The index URLs have a query string with parameters in the format "?size=xx&offset=xx." If a query parameter is omitted, the default value is used.

{| class="wikitable"
!''Query Parameter''
!''Default''
!''Maximum''
!''Notes''
|-
| size
| 50
| 250
| This is the number of elements per page.
|-
| offset
| 0
| N/A
| This is the number of items to offset away from the first item in the list.
|}

===== Example =====

A PHP Example of paging can be found [[PHP_Examples_(Rest_API)| here]].

==== Examples ====

<pre>
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.0
Date: Fri, 04 Dec 2009 19:08:11 GMT
Content-Length: 430

<?xml version="1.0" encoding="utf-8"?>
<domainList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domainList">
<offset>0</offset>
<size>50</size>
<total>1</total>
<domains>
<domain>
<name>customer.com</name>
<accountNumber>123456</accountNumber>
<serviceType>rsemail</serviceType>
</domain>
</domains>
</domainList>
</pre>

<pre>
HTTP/1.1 404 Not Found
Cache-Control: private
Server: Microsoft-IIS/7.0
x-error-message: Customer Not Found
Date: Fri, 04 Dec 2009 19:13:59 GMT
Content-Length: 0
</pre>

<pre>
HTTP/1.1 400 Bad Request
Cache-Control: private
Server: Microsoft-IIS/7.0
x-error-message: Missing required field: type
Date: Fri, 04 Dec 2009 19:17:29 GMT
Content-Length: 0
</pre>

== Examples ==

=== Ruby ===

This examples is written in [http://www.ruby-lang.org/en/ Ruby]. To make the examples shorter, helper methods have been written. These methods are part of a NetMethods module. The contents of the NetMethods module is listed below.

<pre>
require 'server.rb'

server = Server.new

response = server.get '/customers', server.xml_format

#fields = Hash['serviceType' => 'exchange', 'exchangeMaxNumMailboxes' => '4']
#response = server.post '/customers/me/domains/newdomain.com', fields

puts response.code
puts response['x-error-message']
puts response.body
</pre>

<pre>
require 'test/unit/assertions'
require 'net/http'
require 'date'
require 'date/format'
require 'digest/sha1'
require 'base64'
require 'time'

class Server
include Test::Unit::Assertions

def initialize(server='api.emailsrvr.com', version_prefix='/v1', user_key='xxxxxxxxxxxxxxxxxxxx', secret_hash='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
@server = server
@version_prefix = version_prefix
@user_key = user_key
@secret_hash = secret_hash
end

# Response Type Enums

def xml_format
'text/xml'
end

def json_format
'application/json'
end

#
# HTTP Request Verbs
#
def get(url_string, format)
uri = full_uri(url_string)
headers = prepared_headers
headers['Accept'] = format
request = Net::HTTP::Get.new(request_uri(uri), headers)
http_response = make_request request, uri
end

def delete(url_string)
uri = full_uri(url_string)
request = Net::HTTP::Delete.new(request_uri(uri), prepared_headers)
http_response = make_request request, uri
end

def put(url_string, fields_hash)
uri = full_uri(url_string)
request = Net::HTTP::Put.new(request_uri(uri), prepared_headers)
request.set_form_data(fields_hash)
http_response = make_request request, uri
end

def post(url_string, fields_hash)
uri = full_uri(url_string)
request = Net::HTTP::Post.new(request_uri(uri), prepared_headers)
request.set_form_data(fields_hash)
http_response = make_request request, uri
end

#
# HTTP Request Helpers
#
def make_request request, uri
response = Net::HTTP::start(uri.host, uri.port) do |http|
http.request request
end

response
end

def full_uri url_string
URI.parse('http://' + @server + @version_prefix + url_string)
end

def request_uri uri
request = uri.path
if ! uri.query.nil?
request = request + '?' + uri.query
end
request
end

def prepared_headers
headers = Hash.new
headers.merge! headers_auth_creds(@user_key, @secret_hash)
headers['Accept'] = xml_format
headers
end

def headers_auth_creds apiKey, secretKey
userAgent = 'Ruby Test Client'
timestamp = DateTime.now.strftime('%Y%m%d%H%M%S')

data_to_sign = apiKey + userAgent + timestamp + secretKey

hash = Base64.encode64(Digest::SHA1.digest(data_to_sign))
signature = apiKey + ":" + timestamp + ":" + hash

headers = Hash['User-Agent' => userAgent, 'X-Api-Signature' => signature]
end
end
</pre>

=== C# ===

This examples is written in [http://msdn.microsoft.com/en-us/vcsharp/default.aspx C#].

<pre>
using System;
using System.IO;
using System.Net;
using System.Security.Cryptography;
using System.Text;

namespace RestApiClient
{
public class RestApiClient
{
private HttpWebRequest request;
private HttpWebResponse response;
private string baseUrl;
private string apiKey;
private string secretKey;

public RestApiClient(string baseUrl, string apiKey, string secretKey)
{
this.baseUrl = baseUrl;
this.apiKey = apiKey;
this.secretKey = secretKey;
}

public HttpWebResponse Get(string url, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "GET";
SignMessage();
AssignFormat(format);
return GetResponseContent();
}

public HttpWebResponse Post(string url, string data, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "POST";
SignMessage();
AssignFormat(format);
SendFormData(data);
return GetResponseContent();
}

public HttpWebResponse Put(string url, string data, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "PUT";
SignMessage();
AssignFormat(format);
SendFormData(data);
return GetResponseContent();
}

public HttpWebResponse Delete(string url, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "DELETE";
SignMessage();
AssignFormat(format);
return GetResponseContent();
}

private void SendFormData(string data)
{
UTF8Encoding encoding = new UTF8Encoding();
byte[] byteData = encoding.GetBytes(data);
this.request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = byteData.Length;
Stream requestStream = request.GetRequestStream();
requestStream.Write(byteData, 0, byteData.Length);
requestStream.Close();
}

private HttpWebResponse GetResponseContent()
{
try
{
return (HttpWebResponse)request.GetResponse();
}
catch (WebException e)
{
return (HttpWebResponse)e.Response;
}

}

private void SignMessage()
{
var userAgent = "C# Client Library";
this.request.UserAgent = userAgent;
var dateTime = DateTime.UtcNow.ToString("yyyyMMddHHmmss");
var dataToSign = apiKey + userAgent + dateTime + secretKey;
var hash = SHA1.Create();
var signedBytes = hash.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
var signature = Convert.ToBase64String(signedBytes);

request.Headers["X-Api-Signature"] = apiKey + ":" + dateTime + ":" + signature;
}

private void AssignFormat(string format)
{
this.request.Accept = format;
}
}
}
</pre>

=== PHP ===

The PHP Example can be found [[PHP_Examples_(Rest_API)| here]].

Main Page

2020-12-02T23:21:00Z

Matt.Brown: Add Domain Webmail Settings Section

== Introduction ==

The Rackspace Email Rest API provides most of the functions of the Control Panel through a REST-based [http://en.wikipedia.org/wiki/Web_service web API]. Whether it is adding a new customer account, adding mailboxes, or any other of the supported features the API allows your application to administer the changes regardless of your application's language or nature. For more information on RESTful web services refer to the following sites:

[http://www.peej.co.uk/articles/restfully-delicious.html Paul James's Homepage: A RESTful Web service, an example]

[http://en.wikipedia.org/wiki/Representational_State_Transfer#External_links Wikipedia: Representational State Transfer - External Links]

The API is accessible to all with access to Control Panel, including resellers, business customers, enterprise customers, and indirect customers. However, not all operations are available to non-resellers. See the [[Rest_API#Operations|Operations]] section for more details.

The Rackspace Email Soap API Homepage has been moved to [[Soap_API| here]].

== Operations ==

The following pages detail the operations that the API supports. The operations are grouped into sections based on the entity/object types that each operation interacts with. Non-resellers do not have access to all functions.

{| class="wikitable"
!Resource
!Example URI
!Business User Access
|-
| [[Customer_(Rest_API)| Customer]]
| /customers/123456789
| [[Customer_(Rest_API)#Create_Login_Tokens | Create Login Tokens]]
|-
| [[Admin_(Rest_API)| Admin]]
| /customers/123456789/admins/my_admin
| All
|-
| [[Domain_(Rest_API)| Domain]]
| /customers/123456789/domains/example.com
| [[Domain_(Rest_API)#Index| Index]], [[Domain_(Rest_API)#Show| Show]], [[Domain_(Rest_API)#Split Domain Routing| Split Domain Routing]], [[Domain_(Rest_API)#Archiving SSO Login URL| Archiving SSO Login URL]], [[Domain_(Rest_API)#Domain_Public_Folders_.28Reseller_Only.29|Domain Public Folders]], [[Domain_(Rest_API)#Domain Email Everyone| Email Everyone ]], [[Domain_(Rest_API)#Show_Domain_Catch-All_Address | Catch-All Address]]
|-
| [[Domain_Spam_(Rest_API)| Domain Spam Settings]]
| /customers/123456789/domains/example.com/spam/settings
| All
|-
| [[Domain_Webmail_Settings_(Rest_API)| Domain Webmail Settings]]
| /customers/123456789/domains/example.com/spam/settings
| All
|-
| [[Rackspace_Mailbox_(Rest_API)| Rackspace Email Mailbox]]
| /customers/123456789/domains/example.com/rs/mailboxes/john.smith
| All
|-
| [[Rackspace_Mailbox_Spam_(Rest_API)| Rackspace Email Mailbox Spam Settings]]
| /customers/123456789/domains/example.com/rs/mailboxes/john.smith/spam
| All
|-
| [[Rackspace_Storage_Notification_(Rest_API)| Rackspace Storage Notification Settings]]
| /customers/123456789/domains/example.com/rs/storageNotification
| All
|-
| [[Rackspace_Alias(Rest_API)| Rackspace Email Alias]]
| /customers/123456789/domains/example.com/rs/mailboxes/john.smith/alias
| All
|-
| [[Exchange_Mailbox_(Rest_API)| Exchange Mailbox]]
| /customers/123456789/domains/example.com/ex/mailboxes/john.smith
| All
|-
| [[Exchange_Mailbox_Spam_(Rest_API)| Exchange Mailbox Spam Settings]]
| /customers/123456789/domains/example.com/ex/mailboxes/john.smith/spam
| All
|-
| [[Exchange_Contact_(Rest_API)| Exchange Contact]]
| /customers/123456789/domains/example.com/ex/contacts/john.smith
| All
|-
| [[Exchange_Distribution_List_(Rest_API)| Exchange Distribution List]]
| /customers/123456789/domains/example.com/ex/distributionlists/group.name
| All
|-
| [[Exchange_Resource_Mailbox_(Rest_API)| Exchange Resource Mailbox]]
| /customers/123456789/domains/example.com/ex/resources/conference.room
| All
|-
| [[Exchange_Skype_For_Business_(Rest_API)| Exchange Skype For Business]]
| /customers/123456789/domains/example.com/ex/lync/users
| All
|-
| [[Exchange_Public_Folders_(Rest_API)| Exchange Public Folders]]
| /customers/123456789/domains/example.com/ex/publicFolders
| All
|-
| [[SharePoint_(Rest_API)| SharePoint]]
| /customers/123456789/sharepoint/settings
| [[SharePoint_(Rest_API)#Show | Show]]
|}

The examples shown in the operation pages are written in Ruby and extensively use the helper functions shown in the Ruby Examples below.

== Quick Start ==

'''What you need:'''
* A Rackspace Email and Apps Control Panel admin account
* A HTTP class library that supports TLS 1.2 or greater, and the HTTP methods: GET, POST, PUT, DELETE.

'''Making your first API call, an Show Customer request:'''
# Obtain your API keys
#:* Login to [https://cp.rackspace.com Control Panel]
#:* Click the drop down in the top right next to your admin id/account number.
#:* Click Admins & Contacts
#:* Click API Keys
# Set up your client's HTTP request
#:* Set up your client to make calls to a URL beginning with <nowiki>https://api.emailsrvr.com/v1</nowiki>.
#:* Populate the Accept, User-Agent and X-Api-Signature HTTP request headers correctly. This is explained in detail [[#HTTP Headers|here]].
# Make a GET request to /customers/me.
#:* The complete URI will be <nowiki>https://api.emailsrvr.com/v1/customers/me/domains</nowiki>. Use your HTTP library to retrieve the HTTP response code, 'x-error-message' HTTP response header and HTTP response body so that they may be displayed to help debug and determine success.
'''From here:'''
* Learn about the operations you'll be implementing at the subpages [[#Operations|here]].

== Accessing the API ==

Your application should need to make HTTP requests over TLS 1.2 or greater (HTTPS) to our API servers. Most programming languages have this functionality built into their core libraries. In addition to the common GET and POST HTTP methods, the library used will also need to support PUT and DELETE.

For some language's libraries, simply using an URL that starts with https:// will cause the library to use TLS. In some other libraries however some options specific to the library may have to be configured to utilize TLS.

All API calls should be directed to a URL in the following format:
<pre>https://api.emailsrvr.com/(version)/(resource)</pre>

Example:
<pre>https://api.emailsrvr.com/v1/customers/12345678/domains/customerbusiness.com</pre>

=== Versions ===

{| class="wikitable"
!''Supported Versions''
!''URL''
!''Version Documentation''
|-
| v1 (current)
| <nowiki>https://api.emailsrvr.com/v1/</nowiki>
| http://api-wiki.apps.rackspace.com/api-wiki/index.php/Main_Page
|}

The API version number is a component of the URL that is used to access the API. For example, to access the root of the API, the URL is https://api.emailsrvr.com/v1/. Bug fixes and minor non-breaking changes will be made without changing the version number. When major features or breaking changes are introduced, the version number will be incremented. It is not yet determined how many versions are going to be supported at any one time.

'''Using the discontinued v0 API?'''

* If your client consumes v0 of the Admin REST API for Exchange Distribution Lists or Exchange Resource Mailboxes routes, the client must be updated to consume the new behavior in v1.
* If your client does not consume the v0 Admin REST API for Exchange Distribution Lists and Exchange Resource Mailboxes, you simply need to update the base URL (i.e. https://api.emailsrvr.com/v0/…) from v0 to v1. There were no changes to the behavior of the other entities in the API, only their location changed.

{| class="wikitable"
!''Non-breaking Changes''
!''Breaking Changes''
|-
| Adding new fields or attributes to form fields sent
| Changing or deleting any fields in form fields sent
|-
| Adding fields in returned data
| Changing or removing fields in returned data
|-
|
| Changing the URI of any resource
|}

=== Authentication ===

To gain access to the API, your request must include a properly constructed X-Api-Signature HTTP header. Details on what to put in the header are below. To construct the header, you must have the following keys that are generated from the [https://cp.rackspace.com/MyAccount/Administrators/ApiKeys API Keys] page.

{| class="wikitable"
!Key Name
!Description
!Example
|-
| User Key
| A public key that corresponds to your admin id
| ''eGbq9/2hcZsRlr1JV1Pi''
|-
| Secret Key
| A shared secret key
| ''QHOvchm/40czXhJ1OxfxK7jDHr3t''
|}

An unsuccessful authentication will result in a 403 HTTP code.

==== X-Api-Signature Header ====

Format is as follows:
<'''User Key'''>:<'''Timestamp'''>:<'''SHA1 Hash'''> 
Example: ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:46VIwd66mOFGG8IkbgnLlXnfnkU=''

Remember to include the colons between the data strings!

 
'''User Key''': 
This is the public key issued by the Control Panel browser interface.

 
'''Timestamp''': 
The format is YYYYMMDDHHmmss. All values besides year are zero-padded to two spaces. For example, March 08th 2001 at 2:37.25pm would be ''20010308143725''.

{| class="wikitable"
|YYYY
|Four-digit year
|-
| MM
| Month
|-
| DD
| Day
|-
| HH
| Hour in 24h format
|-
| mm
| Minute
|-
| ss
| Second
|}

'''SHA1 Hash''':

A SHA1 (Secure Hash Algorithm) hash must be applied to a string with the following information:

<'''User Key'''><'''User Agent'''><'''Timestamp'''><'''Secret Key'''>

Note that the 'User Agent' must be the exact same as what is specified in the User-Agent HTTP header. Using the above example data, the string before hashing is: ''eGbq9/2hcZsRlr1JV1PiRackspace Management Interface20010308143725QHOvchm/40czXhJ1OxfxK7jDHr3t''

Resulting base-64 SHA1 Hash: ''46VIwd66mOFGG8IkbgnLlXnfnkU=''

Be sure to encode the binary hash, not the hex hash, into base-64. The resulting string should be 28 characters long.

== Using the API ==

=== Requests ===

HTTP requests should be sent to the server with the correct URL, HTTP method, HTTP headers and form data (if needed). The URL specifies the resource, the HTTP method specifies what operation is done on the resource, and form data is used to specify the details of the resource when the resource is added or edited.

The URLs, corresponding HTTP methods, and necessary form data for the desired operations are detailed in the [[#Operations|operation pages]].

If you're getting the HTTP status code 417 see [[Handling HTTP code 417: Expectation failed]]

==== URL ====

The URLs are specifies the resource or resource collection. Objects are organized in a tree collection, starting with customers at the top, then domains, then domain objects next (such as mailboxes, contacts, and distribution lists) and so on. The URLs of the resources and collections accessible are found on the operation pages.

==== HTTP Method ====

It is the HTTP method that specifies what operation will be done on the resource. For example, to get the details of a mailbox a HTTP GET will be done on /customers/12345678/domains/example.com/ex/mailboxes/john.smith. If the mailbox does not exist, a HTTP POST to the same URL with the necessary form data will add the mailbox. Then, a HTTP PUT to the same URL will edit mailbox. And to delete the mailbox, an HTTP DELETE would be used.

The types of operations a certain method performs is outlined below.

{| class="wikitable"
!''HTTP Method''
!''Operations''
!''Response''
|-
|rowspan=2|GET
|Index - returns a list of the resources
|rowspan=2|XML or JSON formatted data
|-
|Show - returns the details of the resource
|-
|POST
|Add - adds a new resource
|rowspan=3|Response code and error message (if applicable) only
|-
|PUT
|Edit - changes the details of the resource
|-
|DELETE
|Delete - deletes the resource
|}

==== HTTP Headers ====

All requests to the API must then include HTTP headers with the following information:

{| class="wikitable"
!''Header Name''
!''Description''
!''Example Header Value''
|-
| Accept
| The requested content type (required for Index and Show actions). Fill this with either 'text/xml' or 'application/json'. See [[#Formats|Response Formats]]
| ''text/xml''
|-
| User-Agent
| An identifier you choose for your client software
| ''Rackspace Management Interface''
|-
| X-Api-Signature
| An authentication string explained in detail [[#X-Api-Signature_Header|here]]
| ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''
|}

==== Form Data ====

When using Add and Edit operations, the details of the resource are sent to the API server via HTTP form data. Your HTTP library should include methods for sending form data along with an HTTP request. The library should by default send the data in the HTTP request body using the 'application/x-www-form-urlencoded' data format.

==== Index Filter/Search ====

The results of Index actions can be filtered/searched. The index URLs can take either one of the query strings: "?startswith=xx" or "?contains=xx," where "xx" is the key word. If the request specifies more than one of these two query strings, a 400 HTTP error will be returned. Different fields will be searched depending on the resource type, see below.

Note that "0-9" is a reserved key word for query string "startswith." It represents any result starting with numbers.

{| class="wikitable"
!''Index Actions''
!''Where the key word will be searched''
|-
| Customer
| Customer name, account number, reference number
|-
| Domain
| Domain name
|-
| Mailbox
| Mailbox name, mailbox display name, custom ID field
|-
| Contact
| Contact display name, external email
|-
| Group
| Group name, group display name
|-
| Mobile Service
| Associated mailbox name, mailbox display name
|-
| Lync Users
| Mailbox name (NOTE: Does not support the startsWith search parameter)
|}

==== Throttling ====

The server limits the number of requests allowed per user in a certain period of time. The number of requests made are logged per minute. Calls that were made correctly with a user's API key, but not completed for any reason, including those exceeding the throttle limit, are included in this count.

If a user is over the throttling limit then a 403 HTTP code will be returned with an "Exceeded request limits" message.

{| class="wikitable"
!''Operation Category''
!''Request Limit''
|-
| GET
| 120 per minute
|-
| PUT, POST, DELETE
| 90 per minute
|-
| POST, PUT, DELETE on a domain
| 2 per minute
|-
| POST, DELETE on alternate domains
| 2 per minute
|-
| Enabling public folders for a domain
| 1 per 5 minutes
|}

==== Examples ====

Index of Exchange Mailboxes:
<pre>
Hypertext Transfer Protocol
GET /v1/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100 HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml
</pre>

Adding New Exchange Mailbox:
<pre>
Hypertext Transfer Protocol
POST /v1/customers/12345678/domains/example.com/ex/mailboxes/john.smith HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Content-Length: 53
[Content length: 53]
Content-Type: application/x-www-form-urlencoded

Line-based text data: application/x-www-form-urlencoded
size=2048&displayName=John%20Smith&password=abcABC123

</pre>

=== Responses ===

==== HTTP Status Code ====

On a successfully executed request, a 200 HTTP Code is returned. If the request was unsuccessful however, an HTTP error code in the 400s or 500s will be returned.

==== HTTP Response Body ====

If the request is an Index or Show request, the request data will be returned in the format specified in the HTTP Body.

===== Formats =====

Requests for data (index and show requests) are returned with XML or JSON data based on what your application populates the [[#HTTP_Headers|HTTP Accept headers]] with.

For XML, populate the header with 'text/xml' (ex: Headers!["Accept"] = "text/xml"). The XML document returned will conform to a published XSD (XML Schema Document). There are many ways to parse the data in an XML document, but we have found that the [http://www.w3schools.com/XPath/default.asp XPath] tree-style traversal has served our purposes. In any case, your application will likely need to use a class library for your chosen method.

For JSON, populate the header with 'application/json' (ex: Headers!["Accept"] = "application/json"). As with XML, a library will likely be needed to parse the data.

==== HTTP Headers ====

The only data returned in the header is the error message (if any).

{| class="wikitable"
!''Header Name''
!''Description''
!''Example Header Value''
|-
| x-error-message
| The error message. See [[#Errors|Errors]].
| Missing required field: name
|}

==== Errors ====

See [[Errors]].

==== Paging ====

The results of Index actions are split into pages to lessen potentially high resource usage. The index URLs have a query string with parameters in the format "?size=xx&offset=xx." If a query parameter is omitted, the default value is used.

{| class="wikitable"
!''Query Parameter''
!''Default''
!''Maximum''
!''Notes''
|-
| size
| 50
| 250
| This is the number of elements per page.
|-
| offset
| 0
| N/A
| This is the number of items to offset away from the first item in the list.
|}

===== Example =====

A PHP Example of paging can be found [[PHP_Examples_(Rest_API)| here]].

==== Examples ====

<pre>
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.0
Date: Fri, 04 Dec 2009 19:08:11 GMT
Content-Length: 430

<?xml version="1.0" encoding="utf-8"?>
<domainList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domainList">
<offset>0</offset>
<size>50</size>
<total>1</total>
<domains>
<domain>
<name>customer.com</name>
<accountNumber>123456</accountNumber>
<serviceType>rsemail</serviceType>
</domain>
</domains>
</domainList>
</pre>

<pre>
HTTP/1.1 404 Not Found
Cache-Control: private
Server: Microsoft-IIS/7.0
x-error-message: Customer Not Found
Date: Fri, 04 Dec 2009 19:13:59 GMT
Content-Length: 0
</pre>

<pre>
HTTP/1.1 400 Bad Request
Cache-Control: private
Server: Microsoft-IIS/7.0
x-error-message: Missing required field: type
Date: Fri, 04 Dec 2009 19:17:29 GMT
Content-Length: 0
</pre>

== Examples ==

=== Ruby ===

This examples is written in [http://www.ruby-lang.org/en/ Ruby]. To make the examples shorter, helper methods have been written. These methods are part of a NetMethods module. The contents of the NetMethods module is listed below.

<pre>
require 'server.rb'

server = Server.new

response = server.get '/customers', server.xml_format

#fields = Hash['serviceType' => 'exchange', 'exchangeMaxNumMailboxes' => '4']
#response = server.post '/customers/me/domains/newdomain.com', fields

puts response.code
puts response['x-error-message']
puts response.body
</pre>

<pre>
require 'test/unit/assertions'
require 'net/http'
require 'date'
require 'date/format'
require 'digest/sha1'
require 'base64'
require 'time'

class Server
include Test::Unit::Assertions

def initialize(server='api.emailsrvr.com', version_prefix='/v1', user_key='xxxxxxxxxxxxxxxxxxxx', secret_hash='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
@server = server
@version_prefix = version_prefix
@user_key = user_key
@secret_hash = secret_hash
end

# Response Type Enums

def xml_format
'text/xml'
end

def json_format
'application/json'
end

#
# HTTP Request Verbs
#
def get(url_string, format)
uri = full_uri(url_string)
headers = prepared_headers
headers['Accept'] = format
request = Net::HTTP::Get.new(request_uri(uri), headers)
http_response = make_request request, uri
end

def delete(url_string)
uri = full_uri(url_string)
request = Net::HTTP::Delete.new(request_uri(uri), prepared_headers)
http_response = make_request request, uri
end

def put(url_string, fields_hash)
uri = full_uri(url_string)
request = Net::HTTP::Put.new(request_uri(uri), prepared_headers)
request.set_form_data(fields_hash)
http_response = make_request request, uri
end

def post(url_string, fields_hash)
uri = full_uri(url_string)
request = Net::HTTP::Post.new(request_uri(uri), prepared_headers)
request.set_form_data(fields_hash)
http_response = make_request request, uri
end

#
# HTTP Request Helpers
#
def make_request request, uri
response = Net::HTTP::start(uri.host, uri.port) do |http|
http.request request
end

response
end

def full_uri url_string
URI.parse('http://' + @server + @version_prefix + url_string)
end

def request_uri uri
request = uri.path
if ! uri.query.nil?
request = request + '?' + uri.query
end
request
end

def prepared_headers
headers = Hash.new
headers.merge! headers_auth_creds(@user_key, @secret_hash)
headers['Accept'] = xml_format
headers
end

def headers_auth_creds apiKey, secretKey
userAgent = 'Ruby Test Client'
timestamp = DateTime.now.strftime('%Y%m%d%H%M%S')

data_to_sign = apiKey + userAgent + timestamp + secretKey

hash = Base64.encode64(Digest::SHA1.digest(data_to_sign))
signature = apiKey + ":" + timestamp + ":" + hash

headers = Hash['User-Agent' => userAgent, 'X-Api-Signature' => signature]
end
end
</pre>

=== C# ===

This examples is written in [http://msdn.microsoft.com/en-us/vcsharp/default.aspx C#].

<pre>
using System;
using System.IO;
using System.Net;
using System.Security.Cryptography;
using System.Text;

namespace RestApiClient
{
public class RestApiClient
{
private HttpWebRequest request;
private HttpWebResponse response;
private string baseUrl;
private string apiKey;
private string secretKey;

public RestApiClient(string baseUrl, string apiKey, string secretKey)
{
this.baseUrl = baseUrl;
this.apiKey = apiKey;
this.secretKey = secretKey;
}

public HttpWebResponse Get(string url, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "GET";
SignMessage();
AssignFormat(format);
return GetResponseContent();
}

public HttpWebResponse Post(string url, string data, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "POST";
SignMessage();
AssignFormat(format);
SendFormData(data);
return GetResponseContent();
}

public HttpWebResponse Put(string url, string data, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "PUT";
SignMessage();
AssignFormat(format);
SendFormData(data);
return GetResponseContent();
}

public HttpWebResponse Delete(string url, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "DELETE";
SignMessage();
AssignFormat(format);
return GetResponseContent();
}

private void SendFormData(string data)
{
UTF8Encoding encoding = new UTF8Encoding();
byte[] byteData = encoding.GetBytes(data);
this.request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = byteData.Length;
Stream requestStream = request.GetRequestStream();
requestStream.Write(byteData, 0, byteData.Length);
requestStream.Close();
}

private HttpWebResponse GetResponseContent()
{
try
{
return (HttpWebResponse)request.GetResponse();
}
catch (WebException e)
{
return (HttpWebResponse)e.Response;
}

}

private void SignMessage()
{
var userAgent = "C# Client Library";
this.request.UserAgent = userAgent;
var dateTime = DateTime.UtcNow.ToString("yyyyMMddHHmmss");
var dataToSign = apiKey + userAgent + dateTime + secretKey;
var hash = SHA1.Create();
var signedBytes = hash.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
var signature = Convert.ToBase64String(signedBytes);

request.Headers["X-Api-Signature"] = apiKey + ":" + dateTime + ":" + signature;
}

private void AssignFormat(string format)
{
this.request.Accept = format;
}
}
}
</pre>

=== PHP ===

The PHP Example can be found [[PHP_Examples_(Rest_API)| here]].

Domain Webmail Settings (Rest API)

2020-12-02T21:31:48Z

Matt.Brown: Fix HTTP Verb

== v1 - Current==

This resource supports reading and setting various Webmail Settings on a specified domain.

'''These settings are only used for domains that have Rackspace Email services'''. Changing these values will have no effect on Exchange only domains.

=== Data Model ===

==== Webmail Settings ====

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Verbs''
!''Description''
|-
| ChatEnabled
| Bool
| GET, PUT
| Whether the Webmail Chat feature is enabled for the domain and shows up in Webmail
|-
| DropboxEnabled
| Bool
| GET, PUT
| Whether the Dropbox feature is enabled for the domain and shows up in Webmail
|-
| PasswordResetEnabled
| Bool
| GET, PUT
| Whether users are allowed to set up their own reset scheme. Regardless of setting, account admins may always reset their password through the Control Panel or API.
|-
| User24HourTime
| Bool
| GET, PUT
| Whether to show time in 24 hour time. Setting this to false results in 12 hour time being shown in Webmail.
|-
| MultiFactorSetting
| String
| GET, PUT
| Determines whether users are allowed to or are forced to set up Multi-Factor Authentication for their mailbox. Valid options are "on", "off", or "forced".
|-
| DropboxEnabled
| Bool
| GET, PUT
| Whether the Dropbox feature is enabled for the domain and shows up in Webmail
|-
| Language
| String
| GET, PUT
| Determines the default language of the Webmail interface for mailboxes. The supported list of language codes is appended below this table.
|-
| DateFormat
| String
| GET, PUT
| Determines the formatting of dates in Webmail. Valid options are "1" for mm/dd/yy or "2" for dd/mm/yy.
|-
| TimeZone
| String
| GET, PUT
| Determines the default timezone of the Webmail interface for mailboxes. The supported list of timezone strings is appended below this table.
|}

Supported languages for Webmail are:
{| class="wikitable"
!''Language''
!''Language Code''
|-
| English
| en_US
|-
| Spanish
| es_ES
|-
| French
| fr_FR
|-
| Chinese
| zh_CN
|-
| German
| de_DE
|-
| Greek
| de_DE
|-
| Italian
| it_IT
|-
| Japanese
| ja_JP
|-
| Polish
| pl_PL
|-
| Portuguese
| pt_BR
|-
| Thai
| th_TH
|}

Supported timezones for Webmail are any valid PHP timezones: https://www.php.net/manual/en/timezones.php

PHP supports various formats, some examples include

<pre>
Etc/GMT+10
Etc/UTC
US/Eastern
EST
America/Buenos_Aires
</pre>

----

=== Read ===

{| class="wikitable"
! Verb
| GET
|-
! URL Format
| /v1/customers/{customer account number}/domains/{domain name}/webmailSettings/
|-
! Description
| Returns Webmail Settings for the specified domain.
|-
! Model
| [[#Webmail_Settings|Webmail Settings]]
|}

HTTP Codes

{| class="wikitable"
! Code
! Condition
|-
| 200 OK
| The information was successfully retrieved.
|-
| 404 Not Found
| The domain does not exist.
|}

<pre>
Request:
GET https://api.emailsrvr.com/v1/domains/example.com/webmailSettings

Response:
200 OK
{
"ChatEnabled": true,
"DropboxEnabled": true,
"PasswordResetEnabled": false,
"Use24HourTime": true,
"MultiFactorSetting": "forced",
"Language": "en_US",
"DateFormat": "1",
"TimeZone": "US/Eastern"
}
</pre>

----

=== Update ===

{| class="wikitable"
! Verb
| PUT
|-
! URL Format
| /v1/customers/{customer account number}/domains/{domain name}/webmailSettings
|-
! Description
| Updates the webmail settings for a particular domain
|-
! Model
| [[#Webmail_Settings|Webmail Settings]]
|}

HTTP Codes

{| class="wikitable"
! Code
! Condition
|-
| 204 No Content
| The request has been accepted and will be processed.
|-
| 404 Not Found
| The domain does not exist.
|}

<pre>
Request:
PUT https://api.emailsrvr.com/v1/domains/example.com/webmailSettings
{
"ChatEnabled": true,
"DropboxEnabled": true,
"PasswordResetEnabled": false,
"Use24HourTime": true,
"MultiFactorSetting": "forced",
"Language": "es_ES",
"DateFormat": "1",
"TimeZone": "US/Eastern"
}

Response:
204 No Content
</pre>

It also supports partial payloads, for example, just changing the Multi-Factor Authentication setting:

<pre>
Request:
PUT https://api.emailsrvr.com/v1/domains/example.com/webmailSettings
{
"MultiFactorSetting": "on"
}

Response:
204 No Content
</pre>

Domain Webmail Settings (Rest API)

2020-12-02T21:31:09Z

Matt.Brown: Add Domain Webmail Settings Section

== v1 - Current==

This resource supports reading and setting various Webmail Settings on a specified domain.

'''These settings are only used for domains that have Rackspace Email services'''. Changing these values will have no effect on Exchange only domains.

=== Data Model ===

==== Webmail Settings ====

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Verbs''
!''Description''
|-
| ChatEnabled
| Bool
| GET, PUT
| Whether the Webmail Chat feature is enabled for the domain and shows up in Webmail
|-
| DropboxEnabled
| Bool
| GET, PUT
| Whether the Dropbox feature is enabled for the domain and shows up in Webmail
|-
| PasswordResetEnabled
| Bool
| GET, PUT
| Whether users are allowed to set up their own reset scheme. Regardless of setting, account admins may always reset their password through the Control Panel or API.
|-
| User24HourTime
| Bool
| GET, PUT
| Whether to show time in 24 hour time. Setting this to false results in 12 hour time being shown in Webmail.
|-
| MultiFactorSetting
| String
| GET, PUT
| Determines whether users are allowed to or are forced to set up Multi-Factor Authentication for their mailbox. Valid options are "on", "off", or "forced".
|-
| DropboxEnabled
| Bool
| GET, PUT
| Whether the Dropbox feature is enabled for the domain and shows up in Webmail
|-
| Language
| String
| GET, PUT
| Determines the default language of the Webmail interface for mailboxes. The supported list of language codes is appended below this table.
|-
| DateFormat
| String
| GET, PUT
| Determines the formatting of dates in Webmail. Valid options are "1" for mm/dd/yy or "2" for dd/mm/yy.
|-
| TimeZone
| String
| GET, PUT
| Determines the default timezone of the Webmail interface for mailboxes. The supported list of timezone strings is appended below this table.
|}

Supported languages for Webmail are:
{| class="wikitable"
!''Language''
!''Language Code''
|-
| English
| en_US
|-
| Spanish
| es_ES
|-
| French
| fr_FR
|-
| Chinese
| zh_CN
|-
| German
| de_DE
|-
| Greek
| de_DE
|-
| Italian
| it_IT
|-
| Japanese
| ja_JP
|-
| Polish
| pl_PL
|-
| Portuguese
| pt_BR
|-
| Thai
| th_TH
|}

Supported timezones for Webmail are any valid PHP timezones: https://www.php.net/manual/en/timezones.php

PHP supports various formats, some examples include

<pre>
Etc/GMT+10
Etc/UTC
US/Eastern
EST
America/Buenos_Aires
</pre>

----

=== Read ===

{| class="wikitable"
! Verb
| GET
|-
! URL Format
| /v1/customers/{customer account number}/domains/{domain name}/webmailSettings/
|-
! Description
| Returns Webmail Settings for the specified domain.
|-
! Model
| [[#Webmail_Settings|Webmail Settings]]
|}

HTTP Codes

{| class="wikitable"
! Code
! Condition
|-
| 200 OK
| The information was successfully retrieved.
|-
| 404 Not Found
| The domain does not exist.
|}

<pre>
Request:
GET https://api.emailsrvr.com/v1/domains/example.com/webmailSettings

Response:
200 OK
{
"ChatEnabled": true,
"DropboxEnabled": true,
"PasswordResetEnabled": false,
"Use24HourTime": true,
"MultiFactorSetting": "forced",
"Language": "en_US",
"DateFormat": "1",
"TimeZone": "US/Eastern"
}
</pre>

----

=== Update ===

{| class="wikitable"
! Verb
| POST
|-
! URL Format
| /v1/customers/{customer account number}/domains/{domain name}/webmailSettings
|-
! Description
| Updates the webmail settings for a particular domain
|-
! Model
| [[#Webmail_Settings|Webmail Settings]]
|}

HTTP Codes

{| class="wikitable"
! Code
! Condition
|-
| 204 No Content
| The request has been accepted and will be processed.
|-
| 404 Not Found
| The domain does not exist.
|}

<pre>
Request:
PUT https://api.emailsrvr.com/v1/domains/example.com/webmailSettings
{
"ChatEnabled": true,
"DropboxEnabled": true,
"PasswordResetEnabled": false,
"Use24HourTime": true,
"MultiFactorSetting": "forced",
"Language": "es_ES",
"DateFormat": "1",
"TimeZone": "US/Eastern"
}

Response:
204 No Content
</pre>

It also supports partial payloads, for example, just changing the Multi-Factor Authentication setting:

<pre>
Request:
PUT https://api.emailsrvr.com/v1/domains/example.com/webmailSettings
{
"MultiFactorSetting": "on"
}

Response:
204 No Content
</pre>

Exchange Mailbox Spam (Rest API)

2020-10-14T22:20:20Z

Matt.Brown: Update route names and get XML payload

__TOC__

== v1 - Current ==

=== Spam Settings ===

==== Show ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/settings</nowiki>

''Description'':

This operation returns the spam settings associated with the mailbox.

''Remarks'':

The Show operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<MailboxSpamSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:MailboxSpamSettings">
<filterLevel>on</filterLevel>
<sendToDomainQuarantine>false</sendToDomainQuarantine>
<quarantineOwner />
</MailboxSpamSettings>
</pre>

''Json Result Example'':

{"filterLevel":"on","sendToDomainQuarantine":false,"quarantineOwner":""}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/settings</nowiki>

''Description'':

This operation will modify the mailbox spam setting. Only 'filterlevel' is the required form field.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterlevel
| string
| Spam filter status, must be 'on' or 'off' or 'exclusive' (Required)
|-
| sendtodomainquarantine
| boolean
| Indicates whether or not send spam to domain quarantine
|-
| quarantineowner
| string
| The email address that quarantine notifications be sent to
|-
| removeQuarantineOwner
| boolean
| Set this flag to "true" to remove quarantine owner
|}

''Remarks'':

Form field "filterlevel" is always required. 
When "filterlevel" is "on", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". 
Changing "filterlevel" to "off" will force "sendtodomainquarantine" to be "false". 
When "filterlevel" is "exclusive", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". In addition, mailbox will only receive email from addresses and IPs on its safelist.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings',
{
'filterlevel' => 'off'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid input for form field 'filterlevel'
| 400
| Invalid filterLevel, input must be: on/off/exclusive
|}

=== Blocklist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/blocklist</nowiki>

''Description'':

This operation returns email address blocklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blocklist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blocklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blocklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blocklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/blocklist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the blocklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blocklist/anyone@spam.com', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blocklist the current domain
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/blocklist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the blocklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blocklist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blocklist
| 400
| abc@junkmail.com is not found on the blocklist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/blocklist</nowiki>

''Description'':

Edit email addresses on the blocklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/blocklist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Blocklist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipblocklist</nowiki>

''Description'':

This operation returns IP blocklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblocklist'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlocklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlocklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlocklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipblocklist/(ip address)</nowiki>

''Description'':

Adds an IP to the blocklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blocklist/216.12.34.1', {}
</pre>

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipblocklist/(ip address)</nowiki>

''Description'':

Removes an IP from the blocklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblocklist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current blocklist
| 400
| 216.12.34.1 is not found on the blocklist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipblocklist</nowiki>

''Description'':

Edit IP addresses on the blocklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/ipblocklist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>

=== Safelist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/safelist</nowiki>

''Description'':

This operation returns email address safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/safelist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/safelist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the safelist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/safelist</nowiki>

''Description'':

Edit email addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/safelist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Safelist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipsafelist</nowiki>

''Description'':

This operation returns IP safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipsafelist/(ip address)</nowiki>

''Description'':

Adds an IP to the ipsafelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipsafelist/(email address)</nowiki>

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the safelist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipsafelist</nowiki>

''Description'':

Edit IP addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/ipsafelist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>

Exchange Mailbox Spam (Rest API)

2020-10-14T21:24:39Z

Matt.Brown: Update route names and get XML payload

__TOC__

== v1 - Current ==

=== Spam Settings ===

==== Show ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/settings</nowiki>

''Description'':

This operation returns the spam settings associated with the mailbox.

''Remarks'':

The Show operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<MailboxSpamSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:MailboxSpamSettings">
<filterLevel>on</filterLevel>
<sendToDomainQuarantine>false</sendToDomainQuarantine>
<quarantineOwner />
</MailboxSpamSettings>
</pre>

''Json Result Example'':

{"filterLevel":"on","sendToDomainQuarantine":false,"quarantineOwner":""}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/settings</nowiki>

''Description'':

This operation will modify the mailbox spam setting. Only 'filterlevel' is the required form field.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterlevel
| string
| Spam filter status, must be 'on' or 'off' or 'exclusive' (Required)
|-
| sendtodomainquarantine
| boolean
| Indicates whether or not send spam to domain quarantine
|-
| quarantineowner
| string
| The email address that quarantine notifications be sent to
|-
| removeQuarantineOwner
| boolean
| Set this flag to "true" to remove quarantine owner
|}

''Remarks'':

Form field "filterlevel" is always required. 
When "filterlevel" is "on", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". 
Changing "filterlevel" to "off" will force "sendtodomainquarantine" to be "false". 
When "filterlevel" is "exclusive", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". In addition, mailbox will only receive email from addresses and IPs on its safelist.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings',
{
'filterlevel' => 'off'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid input for form field 'filterlevel'
| 400
| Invalid filterLevel, input must be: on/off/exclusive
|}

=== Blocklist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/blocklist</nowiki>

''Description'':

This operation returns email address blocklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blocklist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blocklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blocklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blocklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/blocklist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the blocklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blocklist/anyone@spam.com', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blocklist the current domain
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/blocklist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the blocklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blocklist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blocklist
| 400
| abc@junkmail.com is not found on the blocklist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/blocklist</nowiki>

''Description'':

Edit email addresses on the blocklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/blocklist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Blacklist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipblacklist</nowiki>

''Description'':

This operation returns IP blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlacklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlacklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/216.12.34.1', {}
</pre>

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current blacklist
| 400
| 216.12.34.1 is not found on the blacklist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipblacklist</nowiki>

''Description'':

Edit IP addresses on the blacklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/ipblacklist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>

=== Safelist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/safelist</nowiki>

''Description'':

This operation returns email address safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/safelist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/safelist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the safelist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/safelist</nowiki>

''Description'':

Edit email addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/safelist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Safelist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipsafelist</nowiki>

''Description'':

This operation returns IP safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipsafelist/(ip address)</nowiki>

''Description'':

Adds an IP to the ipsafelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipsafelist/(email address)</nowiki>

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the safelist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipsafelist</nowiki>

''Description'':

Edit IP addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/ipsafelist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>

Rackspace Mailbox Spam (Rest API)

2020-10-14T21:16:04Z

Matt.Brown: Update route names and get XML payload

__TOC__

== v1 - Current ==

=== Spam Settings ===

==== Show ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/settings</nowiki>

''Description'':

This operation returns the spam settings associated with the mailbox.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/settings'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<rsMailboxSpamSetting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:RSMailboxSpamSetting">
<filterLevel>on</filterLevel>
<rsEmailSettings>
<spamHandling>toFolder</spamHandling>
<hasFolderCleaner>false</hasFolderCleaner>
<spamFolderAgeLimit>0</spamFolderAgeLimit>
<spamFolderNumLimit>0</spamFolderNumLimit>
<spamForwardingAddress />
</rsEmailSettings>
</rsMailboxSpamSetting>
</pre>

''Json Result Example'':

<pre>
{ "filterLevel":"on",
"rsEmailSettings":{
"hasFolderCleaner":false,
"spamFolderAgeLimit":0,
"spamFolderNumLimit":0,
"spamForwardingAddress":"",
"spamHandling":"toFolder"
}
}
</pre>

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/rs/mailboxes/(mailbox name)/spam/settings</nowiki>

''Description'':

This operation will modify the mailbox spam settings.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterLevel
| string
| This is a required field. Spam filter status: 'on', 'off', or 'exclusive'. Exclusive mode allows only email cleared by the Safelist.
|
|-
| rsEmail.spamHandling
| string
| The string 'toFolder' will deliver the email to the user's Spam folder, 'delete' will delete the mail immediately, 'labelSubject' will prepend [SPAM] to the email's subject line, and 'toAddress' will send the email to a specified folder instead.

Valid Field Combinations:

(toFolder => hasFolderCleaner, spamFolderAgeLimit, spamFolderNumLimit)

(toAddress => spamForwardingAddress)
|-
| rsEmail.hasFolderCleaner
| string
| This field is effective when rsEmail.spamHandling option is set to 'toFolder'. This field controls how the spam that is delivered o the spam folder is handled. There are currently two options supported for handling spam. First option is to set a limit after which the spam gets deleted. One can set limit on the number of days or on the number of spam emails. Second option is to never automatically delete the spam. For both these options to be enabled the rsEmail.hasFolderCleaner field should be set to 'true'.
The folder cleaner fields (hasFolderCleaner, spamFolderAgeLimit, spamFolderNumLimit) are allowed
only when the spamHandling field is set to 'toFolder'. In order to never delete the spam set the spamFolderAgeLimit and spamFolderNumLimit fields to 0.
|-
| rsEmail.spamFolderAgeLimit
| string
| The number of days a message stays in the Spam folder before its deleted. This field is effective only when rsEmail.spamHandling is set to 'toFolder', and 'rs.hasFolderCleaner' is set to 'true'. This field cannot have negative value.
|-
| rsEmail.spamFolderNumLimit
| string
| The maximum number of emails the Spam folder holds. This field is effective only when rsEmail.spamHandling is set to 'toFolder', and 'rs.hasFolderCleaner' is set to 'true'. This field cannot have negative value.
|-
| rsEmail.spamForwardingAddress
| string
| The email address that Spam emails will be redirected to. This field is required when the spamHandling field is set to 'toAddress'
|}

''Example'':
<pre>
put '/customers/100018/domains/resellerallservices.net/rs/mailboxes/unittestexist/spam/settings',
{
'filterLevel' => 'on',
'rsEmail.spamHandling' => 'toFolder',
'rsEmail.hasFolderCleaner' => 'true',
'rsEmail.spamFolderAgeLimit' => '7',
'rsEmail.spamFolderNumLimit' => '100',
}, Formats.xml
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid input for form field 'filterLevel'
| 400
| Invalid FilterLevel: Input must be: on/off/exclusive
|-
| Invalid input for form field 'spamHandling'
| 400
| Invalid RSEmail SpamHandling: Input must be: toFolder/delete/labelSubject/toAddress
|-
| Invalid email address in spam forwarding address
| 400
| Invalid email address
|-
| Empty forwarding address
| 400
| Spam Forwarding Address cannot be empty for spam handling policy: toAddress
|-
| Invalid value for field 'spamFolderAgeLimit'
| 400
| Invalid RSEmail SpamCleanupOption: -1. rsEmail.spamFolderAgeLimit should be non-negative
|-
| Invalid value for field 'spamFolderNumLimit'
| 400
| Invalid RSEmail SpamCleanupOption: -1. rsEmail.spamNumberLimit should be non-negative.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: delete.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: labelSubject.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: toAddress.
|}

=== Blocklist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/blocklist</nowiki>

''Description'':

This operation returns email address blocklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/blocklist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blocklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blocklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blocklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/blocklist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the blocklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/blocklist/anyone@spam.com', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blocklist the current domain
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/blocklist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the blocklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/blocklist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blocklist
| 400
| abc@junkmail.com is not found on the blocklist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/blocklist</nowiki>

''Description'':

Edit email addresses on the blocklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/blocklist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Blocklist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipblocklist</nowiki>

''Description'':

This operation returns IP blocklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipblocklist'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlocklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlocklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlocklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipblocklist/(ip address)</nowiki>

''Description'':

Adds an IP to the blocklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/blocklist/216.12.34.1', {}
</pre>

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipblocklist/(ip address)</nowiki>

''Description'':

Removes an IP from the blocklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipblocklist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current blocklist
| 400
| 216.12.34.1 is not found on the blocklist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipblocklist</nowiki>

''Description'':

Edit IP addresses on the blocklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/ipblocklist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>

=== Safelist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/safelist</nowiki>

''Description'':

This operation returns email address safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/safelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/safelist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/safelist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the safelist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/safelist</nowiki>

''Description'':

Edit email addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/safelist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Safelist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipsafelist</nowiki>

''Description'':

This operation returns IP safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipsafelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipsafelist/(ip address)</nowiki>

''Description'':

Adds an IP to the ipsafelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipsafelist/(email address)</nowiki>

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the safelist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipsafelist</nowiki>

''Description'':

Edit IP addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/ipsafelist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>

Rackspace Mailbox Spam (Rest API)

2020-10-14T21:10:25Z

Matt.Brown: Update route names and get XML payload

__TOC__

== v1 - Current ==

=== Spam Settings ===

==== Show ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/settings</nowiki>

''Description'':

This operation returns the spam settings associated with the mailbox.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/settings'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<rsMailboxSpamSetting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:RSMailboxSpamSetting">
<filterLevel>on</filterLevel>
<rsEmailSettings>
<spamHandling>toFolder</spamHandling>
<hasFolderCleaner>false</hasFolderCleaner>
<spamFolderAgeLimit>0</spamFolderAgeLimit>
<spamFolderNumLimit>0</spamFolderNumLimit>
<spamForwardingAddress />
</rsEmailSettings>
</rsMailboxSpamSetting>
</pre>

''Json Result Example'':

<pre>
{ "filterLevel":"on",
"rsEmailSettings":{
"hasFolderCleaner":false,
"spamFolderAgeLimit":0,
"spamFolderNumLimit":0,
"spamForwardingAddress":"",
"spamHandling":"toFolder"
}
}
</pre>

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/rs/mailboxes/(mailbox name)/spam/settings</nowiki>

''Description'':

This operation will modify the mailbox spam settings.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterLevel
| string
| This is a required field. Spam filter status: 'on', 'off', or 'exclusive'. Exclusive mode allows only email cleared by the Safelist.
|
|-
| rsEmail.spamHandling
| string
| The string 'toFolder' will deliver the email to the user's Spam folder, 'delete' will delete the mail immediately, 'labelSubject' will prepend [SPAM] to the email's subject line, and 'toAddress' will send the email to a specified folder instead.

Valid Field Combinations:

(toFolder => hasFolderCleaner, spamFolderAgeLimit, spamFolderNumLimit)

(toAddress => spamForwardingAddress)
|-
| rsEmail.hasFolderCleaner
| string
| This field is effective when rsEmail.spamHandling option is set to 'toFolder'. This field controls how the spam that is delivered o the spam folder is handled. There are currently two options supported for handling spam. First option is to set a limit after which the spam gets deleted. One can set limit on the number of days or on the number of spam emails. Second option is to never automatically delete the spam. For both these options to be enabled the rsEmail.hasFolderCleaner field should be set to 'true'.
The folder cleaner fields (hasFolderCleaner, spamFolderAgeLimit, spamFolderNumLimit) are allowed
only when the spamHandling field is set to 'toFolder'. In order to never delete the spam set the spamFolderAgeLimit and spamFolderNumLimit fields to 0.
|-
| rsEmail.spamFolderAgeLimit
| string
| The number of days a message stays in the Spam folder before its deleted. This field is effective only when rsEmail.spamHandling is set to 'toFolder', and 'rs.hasFolderCleaner' is set to 'true'. This field cannot have negative value.
|-
| rsEmail.spamFolderNumLimit
| string
| The maximum number of emails the Spam folder holds. This field is effective only when rsEmail.spamHandling is set to 'toFolder', and 'rs.hasFolderCleaner' is set to 'true'. This field cannot have negative value.
|-
| rsEmail.spamForwardingAddress
| string
| The email address that Spam emails will be redirected to. This field is required when the spamHandling field is set to 'toAddress'
|}

''Example'':
<pre>
put '/customers/100018/domains/resellerallservices.net/rs/mailboxes/unittestexist/spam/settings',
{
'filterLevel' => 'on',
'rsEmail.spamHandling' => 'toFolder',
'rsEmail.hasFolderCleaner' => 'true',
'rsEmail.spamFolderAgeLimit' => '7',
'rsEmail.spamFolderNumLimit' => '100',
}, Formats.xml
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid input for form field 'filterLevel'
| 400
| Invalid FilterLevel: Input must be: on/off/exclusive
|-
| Invalid input for form field 'spamHandling'
| 400
| Invalid RSEmail SpamHandling: Input must be: toFolder/delete/labelSubject/toAddress
|-
| Invalid email address in spam forwarding address
| 400
| Invalid email address
|-
| Empty forwarding address
| 400
| Spam Forwarding Address cannot be empty for spam handling policy: toAddress
|-
| Invalid value for field 'spamFolderAgeLimit'
| 400
| Invalid RSEmail SpamCleanupOption: -1. rsEmail.spamFolderAgeLimit should be non-negative
|-
| Invalid value for field 'spamFolderNumLimit'
| 400
| Invalid RSEmail SpamCleanupOption: -1. rsEmail.spamNumberLimit should be non-negative.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: delete.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: labelSubject.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: toAddress.
|}

=== Blocklist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/blocklist</nowiki>

''Description'':

This operation returns email address blocklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/blocklist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blocklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blocklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blocklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/blocklist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the blocklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/blocklist/anyone@spam.com', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blocklist the current domain
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/blocklist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the blocklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/blocklist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blocklist
| 400
| abc@junkmail.com is not found on the blocklist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/blocklist</nowiki>

''Description'':

Edit email addresses on the blocklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/blocklist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Blacklist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipblacklist</nowiki>

''Description'':

This operation returns IP blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipblacklist'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlacklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlacklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/blacklist/216.12.34.1', {}
</pre>

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipblacklist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current blacklist
| 400
| 216.12.34.1 is not found on the blacklist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipblacklist</nowiki>

''Description'':

Edit IP addresses on the blacklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/ipblacklist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>

=== Safelist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/safelist</nowiki>

''Description'':

This operation returns email address safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/safelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/safelist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/safelist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the safelist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/safelist</nowiki>

''Description'':

Edit email addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/safelist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Safelist ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipsafelist</nowiki>

''Description'':

This operation returns IP safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipsafelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipsafelist/(ip address)</nowiki>

''Description'':

Adds an IP to the ipsafelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipsafelist/(email address)</nowiki>

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the safelist
|}

==== Edit ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)/spam/ipsafelist</nowiki>

''Description'':

Edit IP addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/ipsafelist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>

Domain Spam (Rest API)

2020-10-14T21:03:46Z

Matt.Brown: Update route names and get XML payload

== v1 - Current ==

=== Spam Settings ===

==== Show Spam Setting ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/settings</nowiki>

''Description'':

This operation returns the spam settings associated with the domain.

''Remarks'':

The Show operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/settings'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<domainSpamSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:DomainSpamSettings">
<filterLevel>on</filterLevel>
<rsEmailSettings>
<spamHandling>toAddress</spamHandling>
<hasFolderCleaner>false</hasFolderCleaner>
<spamFolderAgeLimit>0</spamFolderAgeLimit>
<spamFolderNumLimit>0</spamFolderNumLimit>
<spamForwardingAddress>someone@mail.com</spamForwardingAddress>
</rsEmailSettings>
<exchangeSettings>
<forwardToDomainQuarantine>on</forwardToDomainQuarantine>
<quarantineOwner>someone@mail.com</quarantineOwner>
<defaultQuarantineOwner>someone@mail.com</defaultQuarantineOwner>
</exchangeSettings>
</domainSpamSettings>
</pre>

''Json Result Example'':

{"filterLevel":"on","rsEmailSettings":{"spamHandling":"toAddress","hasFolderCleaner":false,"spamFolderAgeLimit":0,"spamFolderNumLimit":0,"spamForwardingAddress":"someone@mail.com"},"exchangeSettings":{"forwardToDomainQuarantine":"on","quarantineOwner":"someone@mail.com","defaultQuarantineOwner":"someone@mail.com"}}

==== Edit Spam Setting ====

''URL'':

<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/settings</nowiki>

''Description'':

Edits the domain Spam Settings.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterLevel
| string
| Spam filter status, must be 'on' or 'off' or 'exclusive' (Required)
|-
| overrideUserSettings
| boolean
| Set this flag to "true" to override preferences for all users regardless of their own preferences. Otherwise, it sets preferences only for users who have not set their own.
|-
| rsEmail.spamHandling
| string
| Change settings for Rackspace Email Handling. For the options, see the table below.
|-
| rsEmail.hasFolderCleaner
| boolean
| Turns on/off Spam Folder Cleaner. Requires "rsEmail.spamHandling" to be set to "toFolder".
|-
| rsEmail.spamFolderAgeLimit
| int
| The number of days that email stays the "Spam" folder before being deleted. Requires "rsEmail.hasFolderCleaner" to be set to "true".
|-
| rsEmail.spamFolderNumLimit
| int
| The max number of emails that will be kept in the "Spam" folder. Requires "rsEmail.hasFolderCleaner" to be set to "true".
|-
| rsEmail.spamForwardingAddress
| string
| The address that spams will be forwarded to. Requires "rsEmail.spamHandling" to be set to "toAddress".
|-
| exchange.forwardToDomainQuarantine
| string
| Change settings for Exchange Handling. For the options, see the table below.
|-
| exchange.quarantineOwner
| string
| The address that domain quarantine notifications will be sent to.
|-
| exchange.removeQuarantineOwner
| boolean
| Set this flag to "true" to remove domain quarantine owner.
|-
| exchange.defaultQuarantineOwner
| string
| The address that quarantine notifications will be sent to. This applies to new users and users that have not changed their settings to override.
|-
| exchange.removeDefaultQuarantineOwner
| boolean
| Set this flag to "true" to remove default domain quarantine owner.
|}

Rackspace Email Handling Options:
{| class="wikitable"
!''Value''
!''Description''
|-
| toFolder
| Deliver to Spam folder
|-
| delete
| Delete the email immediately
|-
| labelSubject
| Include "[SPAM]" at the beginning of the subject line
|-
| toAddress
| Deliver to the email address that is specified by "rsEmail.spamForwardingAddress"
|}

Exchange Handling Options:
{| class="wikitable"
!''Value''
!''Description''
|-
| on
| Send all spam to domain quarantine
|-
| off
| Send spam to recipient's quarantine
|-
| nonuser
| Send non-user spam (Contacts, Resources, etc.) to domain quarantine
|}

''Example'':

<pre>
put '/customers/me/domains/example.com/spam/settings',
{
'filterLevel' => 'on',
'rsEmail.spamHandling' => 'toFolder',
'rsEmail.hasFolderCleaner' => 'true',
'rsEmail.spamFolderAgeLimit' => '7',
'rsEmail.spamFolderNumLimit' => '100',
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid input for Filter Level
| 400
| Invalid FilterLevel: high. Input must be: on/off/exclusive
|-
| Invalid input for RSEmail SpamHandling
| 400
| Invalid RSEmail SpamHandling: nonuser. Input must be: toFolder/delete/labelSubject/toAddress
|-
| Invalid input for Exchange ForwardToDomainQuarantine
| 400
| Invalid input for Exchange ForwardToDomainQuarantine: delete. Input must be: on/off/nonuser
|}

=== Blocklist ===

==== Index Blocklist ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/blocklist</nowiki>

''Description'':

This operation returns the email address blocklist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/blocklist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blocklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blocklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blocklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

==== Add Blocklist ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/blocklist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the blocklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/blocklist/anyone@spam.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blocklist the current domain
|}

==== Delete Blocklist ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/blocklist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the blocklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/blocklist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blocklist
| 400
| abc@junkmail.com is not found on the list
|}

==== Edit Blocklist ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/blocklist</nowiki>

''Description'':

Edit email addresses on the blcklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/blocklist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Blocklist ===

==== Index IP Blocklist ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipblocklist</nowiki>

''Description'':

This operation returns IP blocklist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/ipblocklist'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlocklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlocklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlocklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

==== Add IP Blocklist ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipblocklist/(ip address)</nowiki>

''Description'':

Adds an IP to the blocklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/blocklist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Delete IP Blocklist ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipblocklist/(ip address)</nowiki>

''Description'':

Removes an IP from the blocklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/ipblocklist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current blocklist
| 400
| 216.12.34.1 is not found on the blocklist
|}

==== Edit IP Blocklist ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipblocklist</nowiki>

''Description'':

Edit IP addresses on the blocklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/ipblocklist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>

=== Safelist ===

==== Index Safelist ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/safelist</nowiki>

''Description'':

This operation returns email address safelist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/safelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

==== Add Safelist ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/safelist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/safelist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

==== Delete Safelist ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/safelist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/safelist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the list
|}

==== Edit Safelist ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/safelist</nowiki>

''Description'':

Edit email addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/safelist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Safelist ===

==== Index IP Safelist ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipsafelist</nowiki>

''Description'':

This operation returns IP safelist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/ipsafelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

==== Add IP Safelist ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipsafelist/(ip address)</nowiki>

''Description'':

Adds an IP to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/safelist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Delete IP Safelist ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipsafelist/(email address)</nowiki>

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/ipsafelist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the list
|}

==== Edit IP Safelist ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipsafelist</nowiki>

''Description'':

Edit IP addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/ipsafelist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>

Domain Spam (Rest API)

2020-10-14T20:47:30Z

Matt.Brown: Update route names and get XML payload

== v1 - Current ==

=== Spam Settings ===

==== Show Spam Setting ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/settings</nowiki>

''Description'':

This operation returns the spam settings associated with the domain.

''Remarks'':

The Show operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/settings'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<domainSpamSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:DomainSpamSettings">
<filterLevel>on</filterLevel>
<rsEmailSettings>
<spamHandling>toAddress</spamHandling>
<hasFolderCleaner>false</hasFolderCleaner>
<spamFolderAgeLimit>0</spamFolderAgeLimit>
<spamFolderNumLimit>0</spamFolderNumLimit>
<spamForwardingAddress>someone@mail.com</spamForwardingAddress>
</rsEmailSettings>
<exchangeSettings>
<forwardToDomainQuarantine>on</forwardToDomainQuarantine>
<quarantineOwner>someone@mail.com</quarantineOwner>
<defaultQuarantineOwner>someone@mail.com</defaultQuarantineOwner>
</exchangeSettings>
</domainSpamSettings>
</pre>

''Json Result Example'':

{"filterLevel":"on","rsEmailSettings":{"spamHandling":"toAddress","hasFolderCleaner":false,"spamFolderAgeLimit":0,"spamFolderNumLimit":0,"spamForwardingAddress":"someone@mail.com"},"exchangeSettings":{"forwardToDomainQuarantine":"on","quarantineOwner":"someone@mail.com","defaultQuarantineOwner":"someone@mail.com"}}

==== Edit Spam Setting ====

''URL'':

<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/settings</nowiki>

''Description'':

Edits the domain Spam Settings.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterLevel
| string
| Spam filter status, must be 'on' or 'off' or 'exclusive' (Required)
|-
| overrideUserSettings
| boolean
| Set this flag to "true" to override preferences for all users regardless of their own preferences. Otherwise, it sets preferences only for users who have not set their own.
|-
| rsEmail.spamHandling
| string
| Change settings for Rackspace Email Handling. For the options, see the table below.
|-
| rsEmail.hasFolderCleaner
| boolean
| Turns on/off Spam Folder Cleaner. Requires "rsEmail.spamHandling" to be set to "toFolder".
|-
| rsEmail.spamFolderAgeLimit
| int
| The number of days that email stays the "Spam" folder before being deleted. Requires "rsEmail.hasFolderCleaner" to be set to "true".
|-
| rsEmail.spamFolderNumLimit
| int
| The max number of emails that will be kept in the "Spam" folder. Requires "rsEmail.hasFolderCleaner" to be set to "true".
|-
| rsEmail.spamForwardingAddress
| string
| The address that spams will be forwarded to. Requires "rsEmail.spamHandling" to be set to "toAddress".
|-
| exchange.forwardToDomainQuarantine
| string
| Change settings for Exchange Handling. For the options, see the table below.
|-
| exchange.quarantineOwner
| string
| The address that domain quarantine notifications will be sent to.
|-
| exchange.removeQuarantineOwner
| boolean
| Set this flag to "true" to remove domain quarantine owner.
|-
| exchange.defaultQuarantineOwner
| string
| The address that quarantine notifications will be sent to. This applies to new users and users that have not changed their settings to override.
|-
| exchange.removeDefaultQuarantineOwner
| boolean
| Set this flag to "true" to remove default domain quarantine owner.
|}

Rackspace Email Handling Options:
{| class="wikitable"
!''Value''
!''Description''
|-
| toFolder
| Deliver to Spam folder
|-
| delete
| Delete the email immediately
|-
| labelSubject
| Include "[SPAM]" at the beginning of the subject line
|-
| toAddress
| Deliver to the email address that is specified by "rsEmail.spamForwardingAddress"
|}

Exchange Handling Options:
{| class="wikitable"
!''Value''
!''Description''
|-
| on
| Send all spam to domain quarantine
|-
| off
| Send spam to recipient's quarantine
|-
| nonuser
| Send non-user spam (Contacts, Resources, etc.) to domain quarantine
|}

''Example'':

<pre>
put '/customers/me/domains/example.com/spam/settings',
{
'filterLevel' => 'on',
'rsEmail.spamHandling' => 'toFolder',
'rsEmail.hasFolderCleaner' => 'true',
'rsEmail.spamFolderAgeLimit' => '7',
'rsEmail.spamFolderNumLimit' => '100',
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid input for Filter Level
| 400
| Invalid FilterLevel: high. Input must be: on/off/exclusive
|-
| Invalid input for RSEmail SpamHandling
| 400
| Invalid RSEmail SpamHandling: nonuser. Input must be: toFolder/delete/labelSubject/toAddress
|-
| Invalid input for Exchange ForwardToDomainQuarantine
| 400
| Invalid input for Exchange ForwardToDomainQuarantine: delete. Input must be: on/off/nonuser
|}

=== Blocklist ===

==== Index Blocklist ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/blocklist</nowiki>

''Description'':

This operation returns the email address blocklist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/blocklist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blocklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blocklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blocklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

==== Add Blocklist ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/blocklist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the blocklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/blocklist/anyone@spam.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blocklist the current domain
|}

==== Delete Blocklist ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/blocklist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the blocklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/blocklist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blocklist
| 400
| abc@junkmail.com is not found on the list
|}

==== Edit Blocklist ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/blocklist</nowiki>

''Description'':

Edit email addresses on the blcklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/blocklist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Blacklist ===

==== Index IP Blacklist ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipblacklist</nowiki>

''Description'':

This operation returns IP blacklist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/ipblacklist'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlacklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlacklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

==== Add IP Blacklist ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/blacklist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Delete IP Blacklist ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/ipblacklist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current blacklist
| 400
| 216.12.34.1 is not found on the blacklist
|}

==== Edit IP Blacklist ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipblacklist</nowiki>

''Description'':

Edit IP addresses on the blacklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/ipblacklist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>

=== Safelist ===

==== Index Safelist ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/safelist</nowiki>

''Description'':

This operation returns email address safelist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/safelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

==== Add Safelist ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/safelist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/safelist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

==== Delete Safelist ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/safelist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/safelist/anyone@yahoo.com'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the list
|}

==== Edit Safelist ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/safelist</nowiki>

''Description'':

Edit email addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/safelist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
}
</pre>

=== IP Safelist ===

==== Index IP Safelist ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipsafelist</nowiki>

''Description'':

This operation returns IP safelist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/ipsafelist'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

==== Add IP Safelist ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipsafelist/(ip address)</nowiki>

''Description'':

Adds an IP to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/safelist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Delete IP Safelist ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipsafelist/(email address)</nowiki>

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/ipsafelist/216.12.34.1'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the list
|}

==== Edit IP Safelist ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/spam/ipsafelist</nowiki>

''Description'':

Edit IP addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/ipsafelist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
}
</pre>