CONFIDENTIAL

Everyone.net XRC Remote API
Document Version: 1.0.4
Copyright © Everyone.net

Contents

1.Introduction
2.Basics
3.Metadata
4.Object Types
5.Methods
6.Exceptions
7.HTTP POST Transport
8.HTTP GET Transport
9.Name Restrictions
10.DNS Issues
11.Glossary
12.Revision History

Introduction

Welcome to Everyone.net's eXtensible Remote Control. XRC exposes the rich functionality of the Everyone.net email system via a remote API. Everyone.net partners that use XRC often have one or more of the following needs.
  1. Provisioning integration.
    ASPs, ISPs and web hosts usually offer several services to their users in addition to email. When the mailbox and/or email service provisioning must occur transparently to the user during sign-up at the partner's site, XRC is required.
  2. Access to specialized functionality.
    Some features of the Everyone.net email system are not available through the web-based control center. XRC exposes this specialized functionality.
  3. Custom administration tools.
    Partners that wish to provide users with their own branded tools to administer their email service may do so via XRC.

Basics

Typical usage of XRC involves the XRC client (hosted by the partner) sending a request to the XRC server (hosted by Everyone.net). The XRC server processes the request and sends back a response.

XRC rides on top of one of several supported transports, referred to as the XRC transport. The current implementation supports two XRC transports: HTTP POST and HTTP GET. HTTP POST is a robust transport that can handle all of the XRC methods efficiently. HTTP GET is generally simpler to use, but is restricted to passing arguments with small serialized representations.

Every XRC request consists of three parts : metadata, method name, and method arguments. Every XRC response consists of two parts: metadata and return value. Each XRC transport has its own means of transporting these parts to and from the XRC server. Details of each transport are found in HTTP POST and HTTP GET.

XRC supports a single authentication mechanism. This mechanism requires an XRC client to provide its client identifier (clientID) and a password with each request. The XRC server validates the password and XRC client source IP before processing any request. The partner must provide their account representative with the IP addresses they plan to use in both their production and testing environments. Failure to authenticate causes the AUTHENTICATION_FAILURE exception to be thrown by every XRC method.

Metadata

XRC metadata is used to pass auxiliary information such as authentication information and exception codes. All XRC metadata consists of key-value paired strings, where the key is from the set of alphanumeric characters and the value is restricted to be a single line (carriage returns and newlines forbidden). Characters in both the key and the value are taken from the set of unicode characters.

More formally, a key and a value in the metadata are defined as follows: 

key = 1*ALPHANUMERIC
value = *CHAR-NOT-CRLF
ALPHANUMERIC = "A" - "Z" / "a" - "z" / "0" - "9"
CHAR-NOT-CRLF = < any unicode character except \u000D and \u000A >
Again, the XRC transport specifies how these key-value pairs are passed to and from the XRC server.

Request Metadata

Every request must have the following key-value pairs.

Key NameValue Description
version The protocol version, must always be the string "1" (without the quotes).
clientID The clientID of the calling XRC client as a sequence of decimal digits.
password The password for the calling XRC client. If you have a distributor control center account, this password is the same as the distributor admin account password. (The same as the password you use with your distadmin account in DCC.)

Response Metadata

A response will have the following key-value pairs.

Key NameValue Description
version The protocol version, will always be the string "1" (without the quotes).
status An integer that identifies whether the operation was successful (status of zero), and if not identifies the exception by its numerical code. See XRC Exceptions for a mapping of status codes to exceptions.
errorDescription Optional. A human-readable description of the exception when status is non-zero. Note that not all exceptions generate this key-value pair.
server Identifies which machine in the XRC pool handled the request. Used for debugging.
timestamp The time the request was received by the server in milliseconds since Jan. 1, 1970. Used for debugging.

Object Types

All objects in XRC have a type. XRC supports a small set of basic types and an extensible set of application-specific complex types. The set of basic types is unlikely to change over time, however new complex types will be introduced as XRC provides more functionality.

Every XRC object can be serialized into a sequence of bytes, and converted back into an equivalent object from those bytes. The method of serializing and deserializing each object is determined solely by its type. The description of each primitive type describes how to serialize objects of that type. When describing how an object is serialized, a reference may be made to an "output stream". The output stream collects bytes as objects are being serialized and either directly transmits them to the peer, or provides a means of extracting its contents later.

Complex types are similar to structs in the C programming language. They have a number of named fields each with a type of its own. The value of each field must be another XRC object or the special value NULL.

All complex types are serialized in the same manner, therefore serialization details are not provided below for each complex type. The process of serializing an object of complex type is as follows. First, the byte 0x3A (US-ASCII colon) is added to the output stream. Next, the UTF-8 encoded type name is added to the output stream. Next, a list is formed containing all the pairs of field names and field values. Each field value immediately follows its corresponding field name in the list. The list is serialized to the output stream as described in list with one exception: field names are UTF-8 encoded without escaping or sandwiching. This exception is possible because field names are restricted to alphanumeric characters only.

There is no requirement placed on the order of the fields in the list. Therefore, correctly implemented client libraries must not assume any field order. 

complex-type = ":" typename list
typename = 1*ALPHA *ALPHANUMERIC
ALPHA = "A" - "Z" / "a" - "z"

Any method argument or complex type field value may have the special value NULL unless otherwise specified by the method or type requirements. A null value is equivalent to (void *)0 in C, or null in Java, or undef in Perl. A null effectively references "no object". When a null value is serialized it appears as the 5 byte UTF-8 representation of the string "/NULL".

During deserialization of a complex type, if a field is missing the value of that field is set to NULL if NULL is an acceptable value for that field. Otherwise, a SERIALIZE exception is thrown.

Methods

Below are the XRC methods. Each method shows an example of its usage. Notice that whenever an object of type bytes is shown in serialized form, the true serialized form is replaced with {123}[123 bytes ...]. Further notice that in HTTP GET examples, the query string may be truncated if it is too long. In all other cases the serialized form of method arguments and return objects is accurate.

In both HTTP GET and HTTP POST examples, the HTTP headers are shown in both requests and responses. It should be noted that the HTTP headers themselves are not part of the XRC transport request or response documents, but are shown anyways. Other HTTP headers are likely to be present in both requests and responses but are not shown here for brevity.

Method Quick Lookup

Signature
createEmailAlias ( clientID : int, name : string, recipients : list ) : void
createEmailClient ( offerIDs : list, emailDomain : string, webmailHostname : string ) : int
createUser ( clientID : int, offerIDs : list, username : string, password : string ) : int
deleteClient ( clientID : int ) : void
deleteEmailAlias ( clientID : int, name : string ) : void
deleteUser ( clientID : int, username : string ) : void
getClientOffers ( clientID : int ) : list
getClientPassword ( clientID : int ) : string
getEmailAliasRecipients ( clientID : int, name : string ) : List
getEmailServiceCatchAll ( clientID : int ) : string
getQuotaWarningLetter ( clientID : int ) : Letter
getUnreadCountForUserMailbox ( clientID : int, username : string ) : int
getUserOffers ( clientID : int, username : string ) : list
getUserPassword ( clientID : int, username : string ) : string
getWebmailPresentation ( clientID : int ) : WebmailPresentation
getWelcomeLetter ( clientID : int ) : Letter
isAccountNameAvailable ( clientID : int, name : string ) : boolean
listClientIDsOfDistributor ( ) : list
listEmailAliasInfoOfClient ( clientID : int ) : List
listUserNamesOfClient ( clientID : int ) : List
loginWebmail ( clientID : int, username : string ) : string
logoutWebmail ( cv : string ) : void
lookupMXReadyClientIDByEmailDomain ( emailDomain : string ) : int
noop ( ) : void
purgeSuspendedUserAccount ( clientID : int, username : string ) : void
setClientOffers ( clientID : int, offerIDs : List ) : void
setClientPassword ( clientID : int, password : string ) : void
setEmailAliasRecipients ( clientID : int, name : string, recipients : list ) : void
setEmailServiceCatchAll ( clientID : int, catchall : string ) : void
setQuotaWarningLetter ( clientID : int, letter : Letter ) : void
setUserOffers ( clientID : int, username : string, offerIDs : List ) : void
setUserPassword ( clientID : int, username : string, password : string ) : void
setWebmailLogos ( clientID : int, smallLogoImage : bytes, largeLogoImage : bytes ) : void
setWebmailNavbarImages ( clientID : int, inboxImage : bytes, composeImage : bytes, addressesImage : bytes, foldersImage : bytes, searchImage : bytes, optionsImage : bytes, helpImage : bytes, logoutImage : bytes ) : void
setWebmailPresentation ( clientID : int, presentation : WebmailPresentation ) : void
setWelcomeLetter ( clientID : int, letter : Letter ) : void
summarizeEmailClient ( clientID : int ) : EmailClientSummary
summarizeEmailClientsOfDistributor ( ) : List
suspendUser ( clientID : int, username : string ) : void
unsuspendUser ( clientID : int, username : string ) : void

Exceptions

Exceptions come in two forms : system exceptions and application exceptions.

System exceptions can be thrown by any method and indicates a unexpected failure on the part of the XRC client or XRC server. Application exceptions are not unexpected as they simply indicate that the "normal" course of operation could not be followed.

For example an attempt to create a user with a username that is already in use throws an application exception (ACCOUNT_NAME_TAKEN). A failure to properly serialize an argument throws a system exception (PROTOCOL or SERIALIZE).

Exception Quick Lookup

IDName
1PROTOCOL
2UNKNOWN_COMMAND
4IO
5AUTHENTICATION_FAILURE
6SYSTEM_FAILURE
7PERMISSION_DENIED
8ARGUMENT_TYPE_MISMATCH
10UNKNOWN_TYPE
11SYNTAX
13SERIALIZE
200INVALID_ARGUMENT
201EMAIL_SERVICE_ALREADY_SETUP
202WEBMAIL_HOSTNAME_NOT_READY
203EMAIL_DOMAIN_NAME_NOT_READY
204WEBMAIL_HOSTNAME_TAKEN
205EMAIL_DOMAIN_NAME_TAKEN
206ACCOUNT_NAME_TAKEN
207CLIENT_DOES_NOT_EXIST
208INVALID_PASSWORD
209INVALID_ADDRESS
210EMAIL_SERVICE_NOT_READY
211INVALID_WEBMAIL_HOSTNAME
212INVALID_EMAIL_DOMAIN
213USER_DOES_NOT_EXIST
214INVALID_ACCOUNT_NAME
215OFFER_NOT_AVAILABLE
216ALIAS_DOES_NOT_EXIST
217USER_NO_MAILBOX
218EMAIL_SERVICE_NOT_FOUND
219ACCOUNT_NOT_SUSPENDED

HTTP POST Transport

The HTTP POST Transport is the preferred transport for XRC. It is designed to handle arbitrarily large argument and return values efficiently. The XRC server listens for HTTP POST requests at the URL http://xrc.everyone.net/ccc/xrc.

A document of content type application/x-eon-xrc-request transports the request to the XRC server. The document body consists of metadata, a blank line, the method name and the serialized method argument list. 

        post-request = 1*(md-line) line-terminator method-name method-args
        md-line = md-key ":" md-value line-terminator
        line-terminator = LF / CRLF 
        LF = "\n"
        CR = "\r" "\n"
        method-name = 1*ALPHA *ALPHANUMERIC
        method-args = < serialized argument list >

Each metadata key-value pair is placed on its own line, with a colon (":") separating the key from the value. The metadata ends with a single blank line. Lines are terminated by a linefeed (0x0A) and if the linefeed is immediately preceded with a carriage return (0x0D), the carriage return is considered part of the line terminator and not part of the metadata value.

After processing, a response document is generated by the XRC server. This document is of content type application/x-eon-xrc-response. The response document body consists of metadata, a blank line, and the serialized return object. The return object of a method with a void return type will always be NULL. 

        post-response = 1*(md-line) line-terminator return-obj
        return-obj = < serialized return object >

It is important that an XRC client check the status metadata. If the value is non-zero, an exception was thrown and the return object is irrelevant and must be ignored. A correct XRC client implementation should be prepared to handle any exception code, regardless of the method invoked.

HTTP GET Transport

The HTTP GET transport is a convenient means of making requests without requiring a request document. Its primary use is to familiarize partners to the methods. Because of its limitations, HTTP GET should not be used for production work. The XRC server listens for HTTP GET requests at the URL http://xrc.everyone.net/ccc/xrc.

An HTTP GET request is formed by appending a query string to the XRC server URL. The query string is a set of key-value pairs separated by equal signs and joined with ampersands. The keys and values are url encoded per RFC 1738. (This should be recognized as the form submittal method used by web browsers.)

Every request metadata key is a HTTP GET key. In addition, the special key cmd is used for the method name, and the special key args is used for the serialized argument list. There will never be a metadata value with name cmd or args so flattening the key namespace will never pose a problem.

Since the serialized argument list can be very long (especially if one or more of the arguments is of type bytes), HTTP GET cannot be used for all methods. It is ill-advised to use HTTP GET if the total length of the query string exceeds 2048 bytes. Note that limit is after proper url encoding, which will add 200% to the length of non-printable characters. It is for this reason that HTTP POST is the preferred production transport.

The response document is exactly the same as for HTTP POST.

Name Restrictions

A number of names and values used in XRC have restrictions on their format. Those restrictions are described here.

Password

A password must be at least 6 characters long and no more than 24 characters long. All characters must be taken from the set of printable ASCII characters (0x20-0x7e). The first and last character may not be a space (0x20).

Account Name

An account name (either an alias name or username) must be at least one character long and no more than 32 characters long. All characters must be from the set composed of the alphanumerics, the underscore, the hyphen, and the period. The first and last character must be an alphanumeric. It may not contain consecutive non-alphanumeric characters.

Webmail Hostname and Email Domain

A webmail hostname or email domain must satisfy the restrictions for a hostname. A hostname must consist of two or more period separated labels. Each label must have at least one character and must contain only alphanumerics and the hyphen. Hyphens may not appear at the beginning or end of a label nor can they appear consecutively within a label. All labels must be no longer than 63 characters and the last label must not contain any digits. The total length of a hostname cannot exceed 255 characters.

DNS Issues

Setting MX Records

It is critical that MX records for email domains using Everyone.net email are setup properly and maintained. The highest priority MX records for the email domain must target sitemail.everyone.net. It is recommended that a second MX record of lower priority target sitemail2.everyone.net. No other MX records should be assigned to the email domain.

As an example, for the email domain "mydomain.com", the relevant portions of a BIND zone file are shown below. 

mydomain.com.   IN MX      0   sitemail.everyone.net.
mydomain.com.   IN MX      10  sitemail2.everyone.net.

Note that lower priority values for an MX record have higher priority.

Setting CNAME Records

For private label service, it is recommended that the webmail hostname be on a domain other than "everyone.net". To do so a CNAME record must be setup for the desired hostname that targets siteurl.everyone.net. For proper operation, no other DNS records of any type may be assigned to the same hostname.

As an example, for the webmail hostname "webmail.mydomain.com", the relevant portions of a BIND zone file are shown below. 

webmail.mydomain.com. IN CNAME     siteurl.everyone.net.

Note that webmail interfaces located on a subdomain of mail.everyone.net do not require setting up or maintaining CNAME records, but such a configuration does not provide a true private label solution.

Glossary

application exception

An exception that does not imply a system problem, but indicate that the "normal" course of operation of the method could not be followed. For example attempting to create a user with a username that is already in use will throw an application exception.

client

An organization that benefits from one or more Everyone.net services. In the case of the email service, the client owns the domain for which Everyone.net provides email. Every client receives service either from a distributor or directly from Everyone.net. In the former case, the client is said to be "owned" by the given distributor. A Distributor is a client that has the Distribution service.

clientID

An identifier unique to every client in the Everyone.net system. All clients whether they are distribution partners, XRC clients, or clients of distributors have a unique clientID. A clientID is a 32-bit unsigned integer. Distributors need not store clientIDs of their clients in their own database if they key their clients by email domain. The lookupMXReadyClientIDByEmailDomain method provides a fast converter from email domain to clientID.

control center

A web-based administration tool used by client admins and distributor admins to manage a single client account.

CV value

An opaque string that securely embeds the identity of a user. Used by integrated login to pass credentials between partner's site and webmail.

distributor

An organization that provides Everyone.net services to other clients and end users.. Typical examples of distributors are web hosts, ISPs, and ASPs.

distributor control center

A web-based administration tool used by distributors to create, delete, and manage multiple clients.

end user

An individual that uses an Everyone.net service. Every user belongs to exactly one client.

integrated login

A limited form of single sign-on that allows a user to login once at the partner's site and not need to login again when accessing the webmail service.

offer

A collection of options the distributor makes available to its owned clients or users. Examples of offers are "2 MB Mailbox with POP" and "6 MB Mailbox with POP and AntiVirus".

service

A hosted application provided by Everyone.net or a distributor that benefits clients and end users. Examples of services are Email and Distribution.

system exception

An exception that indicates an unexpected problem with the system. The problem could be with either the XRC client or XRC server. Any XRC method can throw a system exception.

URL encoded

The result of URL encoding a string. This process is defined in RFC 1738 and is summarized here. First, the string is converted to bytes via UTF-8 transformation. Next, each byte that is not in the set { 0x41 - 0x5a, 0x61 - 0x7a, 0x30 - 0x39, 0x2d, 0x5f, 0x2e, 0x21, 0x7e, 0x2a, 0x5c, 0x28, 0x29 } is replaced with a three byte sequence whose ASCII interpretation is "%XY". X and Y are the hexadecimal digits of the replaced byte value.

webmail hostname

The hostname portion of the URL that locates a client's webmail interface. For example if the webmail hostname for a client is foobar.com, then users would visit http://foobar.com to access that client's webmail service.

XRC client

Depending on context, either the client software using the XRC protocol to make a request and process a response, or the partner site using such client software.

XRC transport

The means of transporting the metadata, method name, method arguments, and return object between XRC client and XRC server. Two transports are currently offered HTTP POST and HTTP GET.

Revision History

1.0 - 7/31/2002

First public release.

1.0.1 - 8/6/2002

1.0.2 - 9/15/2003

1.0.3 - 10/15/2003

1.0.4 - 6/15/2003