Contents
CHAPTER 1 Overview of the APP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7APP architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
APP client layer . . . . . . . . . . . . . . . . . . . . . . . . . . . 7APP server layer . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
CHAPTER 2 Using the APP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Establishing a secure connection . . . . . . . . . . . . . . . . . . . . . . 8
Specifying the version number . . . . . . . . . . . . . . . . . . . . . . . 8
Logging in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Submitting commands . . . . . . . . . . . . . . . . . . . . . . . . . . 9Command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 9Rules for creating and deleting domains, workgroups, and mailboxes . . . . . . 9Mailbox types . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Legal field values . . . . . . . . . . . . . . . . . . . . . . . . . . 10Special characters . . . . . . . . . . . . . . . . . . . . . . . . . . 11Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Ending the session. . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Timeouts for idle connections . . . . . . . . . . . . . . . . . . . . . 12
CHAPTER 3 APP Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Initializing and terminating commands. . . . . . . . . . . . . . . . . . . . 14
Domain commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Workgroup commands . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Mailbox commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 43General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Options (Settings) . . . . . . . . . . . . . . . . . . . . . . . . . . 71Suspension and resinstatement . . . . . . . . . . . . . . . . . . . . . 79Mailing lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Forward only mailboxes . . . . . . . . . . . . . . . . . . . . . . . 88
CHAPTER 4 Timezone values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
CHAPTER 5 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97APP data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
3
Account Provisioning ProtocolDeveloper’s Guide
Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Input attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Related information . . . . . . . . . . . . . . . . . . . . . . . . 101
Mailbox Folder Names . . . . . . . . . . . . . . . . . . . . . . . . . 102Using Webmail to encode folder names . . . . . . . . . . . . . . . . 102
User name and password rules . . . . . . . . . . . . . . . . . . . . . . 103Mailbox user name . . . . . . . . . . . . . . . . . . . . . . . . 103Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Mailbox account holder . . . . . . . . . . . . . . . . . . . . . . . 104Forward address constraints . . . . . . . . . . . . . . . . . . . . . 104
Parsing rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Some definitions . . . . . . . . . . . . . . . . . . . . . . . . . 105
Whitespace . . . . . . . . . . . . . . . . . . . . . . . . . . 105Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Double-quoted string . . . . . . . . . . . . . . . . . . . . . . 105
Client syntax parsing . . . . . . . . . . . . . . . . . . . . . . . . 105Command . . . . . . . . . . . . . . . . . . . . . . . . . . 105Command Name . . . . . . . . . . . . . . . . . . . . . . . 106Attribute-Value Pairs . . . . . . . . . . . . . . . . . . . . . . 106Attribute Name & double-quoted value. . . . . . . . . . . . . . . 106Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Parsing the value further . . . . . . . . . . . . . . . . . . . . 107
Server syntax parsing. . . . . . . . . . . . . . . . . . . . . . . . 107Response . . . . . . . . . . . . . . . . . . . . . . . . . . 107Status line . . . . . . . . . . . . . . . . . . . . . . . . . . 108Other response data . . . . . . . . . . . . . . . . . . . . . . 108Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Parsing the response further . . . . . . . . . . . . . . . . . . . 109
Protocol syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Related information . . . . . . . . . . . . . . . . . . . . . . . . 111
Java prerequisite . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Example error . . . . . . . . . . . . . . . . . . . . . . . . . . 112Identifying the problem . . . . . . . . . . . . . . . . . . . . . . . 112Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Example of APP usage . . . . . . . . . . . . . . . . . . . . . . . . . 113
4
Account Provisioning ProtocolDeveloper’s Guide
CHAPTER 6 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
5
7
Chapter 1
Overview of the APP
This chapter contains the following topics:
• “APP architecture” on page 7
• “Getting started” on page 7
APP architectureThe Account Provisioning Protocol (APP) provides a command-based, TCP/IP protocol that gives external clients a simplified command set to manage mailbox accounts.
APP client layerAn APP client may be as simple as a small Perl script that assigns new passwords to a group of mailboxes or as complex as a Web-based email front-end that lets users change their individual mailbox preferences. All APP clients contain code that calls one or more of the APP commands.
The APP requires a secure connection between the server and a client. Your APP client should initiate a connection through a secure tunnel client that provides SSL encryption using port 4449.
APP server layerThe APP client invokes commands in the APP server. The APP server, in turn, carries out the commands, which modify mailboxes or other OpenSRS services.
Getting started
TO GET STARTED WITH THE APP
1) Install a secure tunnel client to create a secure socket layer for your sessions.
2) Understand how to initialize and test your sessions. See “Using the APP” on page 8.
Once you learn the basics, use the APP command list for reference. See Chapter 3, “APP Commands.”
Chapter 2
Using the APP
OverviewHere are general steps for using the APP. The topics which follow this provide more detail.
TO WORK WITH THE APP
1) Use port 4449 to establish a secure connection to:
• test (for development and testing) at admin.test.hostedemail.comor
• production server at admin.hostedemail.com
See “Establishing a secure connection” on page 8.
2) Specify the APP version number.
See “Specifying the version number” on page 8.
3) Log in.
See “Logging in” on page 9.
4) Submit commands.
See “Submitting commands” on page 9.
5) End the session.
See “Ending the session” on page 12.
In general, you don’t perform these steps manually (by typing them in a TELNET session, for example). Instead, you write a script that performs these steps in the order listed.
Establishing a secure connectionSubmit the appropriate commands for the secure tunnel client you have installed.
Specifying the version numberThe APP always expects the following command first:
VER VER=”3.4” <CRLF>. <CRLF>
8
Account Provisioning ProtocolDeveloper’s Guide
Replace 3.4 with the current version of the APP.
NOTE You must enter a RETURN character followed by a period and then another RETURN after each command you send to the APP.
Logging inLOGIN USER="user-admin" DOMAIN="domain" PASSWORD="password" <CRLF> . <CRLF>
Replace user-admin, domain, and password with the appropriate values of your administrator account.
Submitting commandsThis section explains the syntax and rules for submitting commands.
Command syntaxThe template for a command is as follows:
command attribute=”value” <CRLF>. <CRLF>
Commands consist of a command, followed by white space, followed by zero or more attribute-value pairs separated by white space, followed by a carriage-return with a line-feed (indicated by <CRLF>), a period, and another carriage-return with a line-feed. The values must be enclosed by double quotes.
Valid white space characters are Space, Tab, and Carriage-return/line-feed.
Rules for creating and deleting domains, workgroups, and mailboxes
Hierarchy A strict hierarchy governs the creating and deleting of domains, workgroups, and mailboxes. Listed in order from highest to lowest, that order is company, domain, workgroup, and mailbox. For example, if you want to delete a domain using the APP, the workgroups and mailboxes within a domain must be deleted before that operation will work. Likewise, a user cannot create mailboxes in a specified domain if that domain doesn’t already exist.
Case-insensitive The APP changes to lowercase all mailbox names (including alias mailboxes, group aliases, and forward-only mailboxes), domain names, and workgroup names.
Chapter 2 Using the APP Logging in 9
Account Provisioning ProtocolDeveloper’s Guide
Mailbox typesMailbox accounts can function as one of four possible types: regular mailbox, alias, forwardonly, or filteronly.
In the OpenSRS provisioning system, the mailbox type will change depending on how the mailbox is actually being used. This means that your account billing is more accurate as it is based on what your customers actually do with their mailboxes rather than the way the mailboxes were originally created. For example, if you create an account as a regular mailbox, and then enable it for forwarding and turn off the keep copy flag, you will be charged the rate for a forwardonly account rather than a full mailbox. The type is reflected in the APP command results, so, for example, the GET_DOMAIN_MAILBOXES command shows the account as a forwardonly even though you originally created it as a regular mailbox.
NOTE There used to be one additional type - group alias - however, since group aliases have always operated as forwardonly accounts, they are now displayed that way. The existing group alias APP commands continue to work and are equivalent to the associated forward only commands, for example, the CREATE_GROUP_ALIAS_MAILBOX command is equivalent to the CREATE_MAILBOX_FORWARD_ONLY command.
Legal field valuesThe following table shows the legal field values for APP data types.
Data type Length Syntax
host 90 Valid domain name (lowercase — APP automatically converts uppercase characters).
domain 64 Valid domain name (lowercase — APP automatically converts uppercase characters).
workgroup 30 Starts and ends in a lowercase alphanumeric, otherwise lowercase alphanumeric, hyphen, underscore, or period.
mailbox 64 Same as for workgroup.
password 54 Any printable ASCII characters. For guidelines on creating passwords, see “User name and password rules” on page 103.
Chapter 2 Using the APP Submitting commands 10
Account Provisioning ProtocolDeveloper’s Guide
Special charactersThe following ASCII characters has special meaning in the TELNET interface and should not be entered in APP command attributes.
UnicodeIt is possible for some attributes, such as name, to have unicode values. APP replaces any Unicode with "=[UNICODE]=" in the response. For example:
Request
get_mailbox domain="b.com" mailbox="b"
Response
OK 0 Success
MAILBOX="b" DOMAIN="b.com" BRAND="dddddd" FIRST_NAME="=[UNICODE]="
LAST_NAME="" PHONE="56546" FAX="" TITLE="loafer" PASSWORD="{MD5}$1
$TaXXtF2v$SvZ4SrOZpAVtkWwJxaKfV0" TIMEZONE="Pacific/Wake" LANG="en"
FILTERONLY="F" SPAM_TAG="" SPAM_FOLDER="Spam" SPAM_LEVEL="NORMAL"
first name 30 UTF-8 characters. For guidelines on assigning account names, see “User name and password rules” on page 103.
last name 30 UTF-8 characters. For guidelines on assigning account names, see “User name and password rules” on page 103.
Data type Length Syntax
ASCII number character APP behavior
3 ^C Stops responding and times out after 2 minutes
5 ^E May or may not ignore irregular behavior
26 ^Z Stops responding and times out after 2 minutes
28 ^\ Stops responding and times out after 2 minutes
29 ^] Comes to TELNET prompt
Chapter 2 Using the APP Submitting commands 11
Account Provisioning ProtocolDeveloper’s Guide
Ending the session
QuitThe QUIT command terminates your session.
QUIT <CRLF>. <CRLF>
The server automatically closes its TCP/IP connection.
Timeouts for idle connectionsYour TELNET session will time out if the connection is idle past a certain time period. The default timeout is two minutes. Contact your customer support person if idle timeouts are a problem for you.
Chapter 2 Using the APP Ending the session 12
Chapter 3
APP Commands
The APP commands are listed here, arranged by usage:
• “Initializing and terminating commands” on page 14
• “Domain commands” on page 16
• “Workgroup commands” on page 39
• “Mailbox commands” on page 43
Also see “Command syntax” on page 9.
Each command is shown with a full example of its syntax; you should replace the sample values with your own values. Some examples may appear broken across several lines; however, this is for illustration purposes only, and your commands should appear on a single line.
Some commands require that the user have a certain level of administration privilege; for example, only Company Administrators can create or delete domains. Permission levels are listed under Prerequisites in the following sections.
Also see the glossary definition for “administration privileges” on page 116.
Permission Can be executed by
Company A company administrator in the same company
Domain The above plus domain administrator in same domain
Workgroup All the above plus workgroup administrator in same workgroup
Mailbox All the above plus mailbox owner
13
Account Provisioning ProtocolDeveloper’s Guide
Initializing and terminating commands
VER
Syntax VER VER="<x.x>"
Description Tells the server what version the client is. This must be the first command issued. For example:
VER VER=”3.4”
Prerequisites None
Required VER – Version number of client. Command takes 3.4, 3.5, or 3.6.
Optional None
Errors 6 Unsupported version
LOGIN
Syntax LOGIN USER="<name>" DOMAIN="<domain>" PASSWORD="<pwd>"
Description Authenticates a user to the APP server. For example:
LOGIN USER="ralph" DOMAIN="example.com" PASSWORD="5lKnet"
Prerequisites Passwords must be printable characters and not include spaces. For guidelines on creating passwords, see “User name and password rules” on page 103.
Required • USER – Username
• DOMAIN – Domain name
• PASSWORD – Password
Optional None
Errors • 7 Invalid login
• 15 Invalid password syntax
Chapter 3 APP Commands Initializing and terminating commands 14
Account Provisioning ProtocolDeveloper’s Guide
Also see the glossary definition for “administration privileges” on page 116.
QUIT
Syntax QUIT
Description Terminates APP session.
Prerequisites None
Required None
Optional None
Errors None
Chapter 3 APP Commands Initializing and terminating commands 15
Account Provisioning ProtocolDeveloper’s Guide
Domain commands
CREATE_DOMAIN
Syntax CREATE_DOMAIN DOMAIN="<domain>" [TIMEZONE="<zone>"][LANGUAGE="<language>"][FILTERMX="<domain.tld:port>"][SPAM_TAG="<tag>"][SPAM_FOLDER="<folder>"][SPAM_LEVEL="<level>"]
Description Adds a new domain. Automatically creates the workgroup “staff.
Prerequisites Company (Customer) level permission
Required • DOMAIN
Domain name; the domain must not already exist.
Optional • TIMEZONETime zone for the domain. See Appendix 4, “Timezone values.”
• LANGUAGEThe default language for all mailboxes in the domain. Defaults to "en" if not set. Valid values are: da, en, es, de, fr, it, nl, no, pt_BR, and sv.
• FILTERMXThe Email Exchange (MX) record to which any filter-only accounts direct messages released from spam quarantine. Valid values are hostname and IP address. Both must formats must specify a port.
• SPAM_TAGThe value of this field is appended to the subject of any message identified as spam. Max. 30 char.
• SPAM_FOLDERThe folder into which spam is delivered for all mailboxes in the domain. If not specified, the domain default is Spam. Max. 30 char.
• SPAM_LEVELThe agressiveness level of spam filtering. Valid values are NORMAL, HIGH, VERY HIGH, or "" (no value). When set to NORMAL, most spam is caught. When set to HIGH or VERY HIGH, more spam is caught, but the likelihood that non-spam messages (false positives) will be labelled as spam increases accordingly.
Returns When the command is issued correctly, APP returns the following message: OK 0 Domain created.
Chapter 3 APP Commands Domain commands 16
Account Provisioning ProtocolDeveloper’s Guide
Errors • 4 Permission denied
• 8 Invalid domain name syntax
• 9 Domain name already exists
• 10 Nonexistent domain (only in version 3.5 and earlier)
• 104 Domain name is blacklisted
• 111 Invalid SPAM_LEVEL
CREATE_DOMAIN_ALIAS
Syntax CREATE_DOMAIN_ALIAS DOMAIN="<existing domain>" ALIAS="<new domain alias>"
Description Creates an alias domain.
Prerequisites Company (Customer) level permission.
Required • DOMAIN
• ALIAS
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK O Alias created.
Errors • 4 Permission denied
• 8 Invalid domain name syntax
• 9 Domain name already exists
• 10 Nonexistent domain (only in version 3.5 and earlier)
• 104 Domain name is blacklisted
DELETE_DOMAIN
Syntax DELETE_DOMAIN DOMAIN="<domain>" [CASCADE="T|F"]
Description Removes a domain (including all workgroups and mailboxes if CASCADE is set to T). For example:
DELETE_DOMAIN DOMAIN="example.com" CASCADE="T"
Prerequisites Company-level permissions
CREATE_DOMAIN
Chapter 3 APP Commands Domain commands 17
Account Provisioning ProtocolDeveloper’s Guide
Required • DOMAIN Domain name
Optional • CASCADEBoolean T or F, F by default.Cascade=”F” (or left blank) only deletes the specified domain if it contains no workgroups or mailboxes; otherwise, the command returns error 18 and deletes nothing. Cascade=”T” enables the command to delete all the workgroups and mailboxes in the domain, if any exist. If the domain has more than 10,000 mailboxes, the command displays error 28 and deletes nothing.
• LIMITOverrides the default limit of 10,000, and allows you to specify the maximum number of mailboxes allowed.
Returns When the command is issued correctly, APP returns the following message:OK 0 Domain deleted.
In version 3.6 and later, when CASCADE is specified, the response includes STATUS. For example:
STATUS 1 Deleted user [email protected] 2 Deleted user [email protected] 3 Deleted user [email protected] 4 Deleted workgroup staffOK 0 Domain deleted
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 18 Related workgroups exist (You tried to delete a domain that contains workgroups, and CASCADE is not set to T.)
• 28 Too many mailboxes for cascade delete (current mailbox count > current limit)
DELETE_DOMAIN_ALIAS
Syntax DELETE_DOMAIN_ALIAS ALIAS="<domain alias to be deleted>"
Description Deletes an alias domain.
Prerequisites Company (Customer) level permission.
Required • ALIAS
Optional None.
DELETE_DOMAIN
Chapter 3 APP Commands Domain commands 18
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:OK 0 Alias deleted.
Errors • 4 Permission denied
• 8 Invalid domain name syntax
• 10 Nonexistent domain (only in version 3.5 and earlier)
CREATE_DOMAIN_WELCOME_EMAIL
Syntax CREATE_DOMAIN_WELCOME_EMAIL DOMAIN="<domain>"WELCOME_TEXT="<welcome_text>"WELCOME_SUBJECT="<welcome_subject>"FROM_NAME="<from_name>"FROM_ADDRESS="<from_address>"CHARSET="utf8"MIME_TYPE="text/plain" or "text/html"
Description Creates a welcome message that is sent to every new user who registers on the domain. For example:CREATE_DOMAIN_WELCOME_EMAIL DOMAIN="example.com" WELCOME_TEXT="Hello <name>{4} {5}! Thanks for registering! Your e-mail ID {0}@{1} <[email protected]> has been successfully created." WELCOME_SUBJECT="Welcome to example.com" FROM_NAME="System Administrator" FROM_ADDRESS="[email protected]" CHARSET="utf8" MIME_TYPE="text/html"
If you issue the command more than once, subsequent commands overwrite the earlier messages.
Prerequisites Company (Customer) level administration or domain administration permission.
DELETE_DOMAIN_ALIAS
Chapter 3 APP Commands Domain commands 19
Account Provisioning ProtocolDeveloper’s Guide
Required • DOMAIN
Domain name. The domain must already exist.
• WELCOME_TEXT
The welcome message text. There are no limitations on the size of the message; however, we recommend that it is no more than 32000 characters.
In the welcome email text, the following substitution variables may be used:
• {0}—Mailbox name
• {1}—Domain name
• {4}—First name
• {5}—Last name
For example, suppose a new user, [email protected], registers using his first name “Bill”, his last name “Smith”, then the welcome message used in the command example above is reformatted as:
“Hello Bill Smith! Thanks for registering! Your e-mail ID [email protected] has been successfully created.”
• WELCOME_SUBJECT
The subject line of the message; must be less than 4000 characters.
• FROM_NAME
Name of the sender; must be UTF-8 so that international characters are supported. Any other format results in a syntax error.
• FROM_ADDRESS
Must be a valid email address. Use the full address, including the domain.
• CHARSET
Must be utf8.
• MIME_TYPE
Can be text/plain or text/html. If WELCOME_TEXT is plain, then MIME TYPE should be text/plain; if WELCOME_TEXT is HTML, then MIME_TYPE should be text/html.
Optional None
Returns When the command is issued correctly, APP returns the following message:OK 0 Welcome Email attributes created for the domain.
CREATE_DOMAIN_WELCOME_EMAIL
Chapter 3 APP Commands Domain commands 20
Account Provisioning ProtocolDeveloper’s Guide
Errors • 1 Syntax error (if one or more of the required parameters are not present or are incorrect)
• 5 Internal system error (if failures occur when APP invokes the back end DB procedures)
• 8 Invalid domain name syntax. Domain does not comply with RFC conventions.
• 10 Nonexistent domain (only in version 3.5 and earlier)
GET_COMPANY_DOMAINS
Syntax GET_COMPANY_DOMAINS [LIMIT="<n>"]
Description Returns a list of domains within the current company. For example:
GET_COMPANY_DOMAINS LIMIT=“200”
Prerequisites Company-level permissions
Required None
Optional • LIMITRestricts the size of the list returned (the default is 1,000,000). LIMIT must be a positive integer. The command does not return errors on non-valid LIMIT values.
CREATE_DOMAIN_WELCOME_EMAIL
Chapter 3 APP Commands Domain commands 21
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:In version 3.4:
DOMAIN CREATE_DATE"example1.com","01/01/2004""example2.com","01/01/2004""example3.com","01/01/2004"
NOTE In version 3.4, this command always returns 01/01/2004 as the create_date.
In versions 3.5 and later:
OK 0 SuccessDOMAIN,TYPE,MAILBOX_COUNT,FORWARD_COUNT,ALIAS_COUNT"example1.com","domain","0","0","0","0""example2.com","domain","0","0","0","0""example3.com","domain","0","0","0","0""example4.com","domain","0","0","0","0""example5.com","domain","0","0","0","0"
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 48 Company has too many domains
DELETE_DOMAIN_WELCOME_EMAIL
Syntax DELETE_DOMAIN_WELCOME_EMAIL DOMAIN="<domain>"
Description Deletes a previously configured domain welcome email message. New users who register on the domain after this command is run, do not receive a welcome message. For example:
DELETE_DOMAIN_WELCOME_EMAIL DOMAIN="example.com"
Prerequisites Company (Customer) level administration or domain administration permission. domain must already exist.
Required • DOMAIN
Domain name; the domain must exist.
Optional NONE
Returns When the command is issued correctly, APP returns the following message:
OK 0 Welcome Email attributes deleted for the domain.
GET_COMPANY_DOMAINS
Chapter 3 APP Commands Domain commands 22
Account Provisioning ProtocolDeveloper’s Guide
Errors • 1 Syntax error (if the DOMAIN parameter is not specified)
• 5 Internal system error (if failures occur when APP invokes the back end DB procedures)
• 8 Invalid domain name syntax. Domain does not comply with RFC conventions.
• 10 Nonexistent domain (only in version 3.5 and earlier)
GET_DOMAIN
Syntax GET_DOMAIN DOMAIN="<domain>"
Description Display details about a domain. For example:
GET_DOMAIN DOMAIN="example.com"
Prerequisites Domain-level permissions or higher
Required The specified domain must exist.
DELETE_DOMAIN_WELCOME_EMAIL
Chapter 3 APP Commands Domain commands 23
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:In version3.4
OK 0 SuccessDOMAIN= "example.com" BRANDNAME= "<brand> " CATCHALLUSER= " " INBOUND SMTP= "mx.cust.example.hosstedemail.com " IP= "mail.cust.example.hostedemail.com " NAME= "example.com " OUTBOUNDSMTP= "smtp.cust.example.hostedemail.com " PARENT= " " QUESTION= " " SPAM_TAG= "SPAM " SPAM_FOLDER= "SPAM " SPAM_LEVEL= "NORMAL" DISABLED= "F "
In version3.5
OK 0 SuccessDOMAIN= "example.com" BRANDNAME= "<brand> " CATCHALLUSER= " " INBOUND SMTP= "mx.cust.example.hosstedemail.com " IP= "mail.cust.example.hostedemail.com " NAME= "example.com " OUTBOUNDSMTP= "smtp.cust.example.hostedemail.com " SPAM_TAG= "SPAM " SPAM_FOLDER= "SPAM " SPAM_LEVEL= "NORMAL" DISABLED= "F "ALIASES="bb.com,ba.com,bd.com
• BRANDNAMEThe brand associated with this domain.
• CATCHALLUSERCatch-all mailbox account for this domain.
• DOMAINThe name of the domain (e.g. "example.com").
• INBOUNDSMTPInbound hostname.
• IPDomain hostname.
• NAMEDomain name.
GET_DOMAIN
Chapter 3 APP Commands Domain commands 24
Account Provisioning ProtocolDeveloper’s Guide
• OUTBOUNDSMTPOutbound hostname.
• SPAM_TAGA text tag appended to any the subject of any messages identified as spam. Empty if no tag is specified. Max. 30 char.
• SPAM_FOLDERThe folder to which messages identified as spam are delivered. This value is empty if no folder has been specified; however, the system default of Spam will be applied to the domain.Max. 30 char.
• SPAM_LEVELThe agressiveness level of spam filtering. Value may be NORMAL, HIGH, VERY HIGH, or " " (not set).
• DISABLEDIndicates whether the domain is disabled. Valid values are T and F.
Errors 10 Nonexistent domain (only in version 3.5 and earlier)
GET_DOMAIN_BRAND
Syntax GET_DOMAIN_BRAND DOMAIN= "<domain>"
Description Display details about a domain. For example:
GET_DOMAIN_BRAND DOMAIN= "example.com "
Prerequisites Domain-level permissions or higher
Required The specified domain must exist.
Returns When the command is issued correctly, APP returns the following message:OK 0 successBRANDCODE= "<code>"
• BRANDCODEThe name of the brand that is associated with this domain.
Errors 10 Nonexistent domain (only in version 3.5 and earlier)
GET_DOMAIN
Chapter 3 APP Commands Domain commands 25
Account Provisioning ProtocolDeveloper’s Guide
CHANGE_DOMAIN
Syntax CHANGE_DOMAIN DOMAIN="<domain_name>"[LANGUAGE="<language>"][TIMEZONE="<zone>"][FILTERMX="<domain.tld:port>"][SPAM_TAG="<tag>"][SPAM_FOLDER="<folder>"][SPAM_LEVEL="<level>"]
Description Changes the settings for a domain.
Prerequisites Domain-level permissions
Required • DOMAINDomain name. DOMAIN must already exist.
• At least one optional argument.
Chapter 3 APP Commands Domain commands 26
Account Provisioning ProtocolDeveloper’s Guide
Optional • LANGUAGEThe default language for all mailboxes in the domain. Defaults to "en" if not set. Valid values are as follows: da, en, es, de, fr, it, nl, no, pt_BR, and sv.TIMEZONETime zone for the domain. See Appendix 4, “Timezone values.”
• FILTERMXThe Email Exchange (MX) record to which any filter-only accounts direct messages released from spam quarantine. Valid values are hostname and IP address. Both must formats must specify a port.
• SPAM_TAGThe value of this field will be appended to the subject of any message identified as spam. To remove an existing tag, as opposed to overwriting it, leave the value empty (i.e., SPAM_TAG="").Maximum 30 characters.
• SPAM_FOLDERSpecifies the folder into which spam will be delivered for all future created mailboxes in the domain. Max. 30 char.
NOTE All existing mailboxes will retain their current domain level setting. If you need to change the SPAM_FOLDER for these mailboxes, it will have to be done at the mailbox level . See “CHANGE_MAILBOX” on page 48.
• SPAM_LEVELThe agressiveness level of spam filtering. Valid values are NORMAL, HIGH, VERY HIGH, or "" (no value). When set to NORMAL, most spam is caught. When set to HIGH or VERY HIGH, more spam is caught, but the likelihood that non-spam messages (false positives) will be labelled as spam increases accordingly.
Returns When the command is issued correctly, APP returns the following message:OK 0 Domain is updated.
Errors • 4 Permission denied
• 8 Invalid domain name syntax
• 10 Nonexistent domain (only in version 3.5 and earlier)
• 37 Invalid domain type
• 111 Invalid SPAM_LEVEL
CHANGE_DOMAIN
Chapter 3 APP Commands Domain commands 27
Account Provisioning ProtocolDeveloper’s Guide
SET_DOMAIN_ADMIN
Syntax SET_DOMAIN_ADMIN DOMAIN="<domain>"MAILBOX="<mailbox>"[STATE="T|F"]
Description Grants or removes administration privileges over the domain to which the mailbox already belongs. For example:
SET_DOMAIN_ADMIN DOMAIN="example.com" MAILBOX="foo" STATE="T"
If adding domain-administrator, this command tries to remove any other administrator privileges the mailbox already has (Workgroup, Company), and fails if the caller has insufficient permission to do so. If removing privileges, this command returns OK 0 if the mailbox did not have Domain administrator in the first place.
NOTE SET_DOMAIN_ADMIN replaces the deprecated commands CREATE_DOMAIN_ADMIN and DELETE_DOMAIN_ADMIN.
Prerequisites Company-level permissions.
Required • DOMAIN
• MAILBOX
Optional • STATEBoolean T or F.
Returns When the command is issued correctly, APP returns the following message:OK 0
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is one of type: alias, or forward_only
Chapter 3 APP Commands Domain commands 28
Account Provisioning ProtocolDeveloper’s Guide
SET_DOMAIN_BRAND
Syntax SET_DOMAIN_BRAND DOMAIN="<domain>" BRAND_CODE="<code>"
Description Assigns a brand to the domain
For example:
SET_DOMAIN_BRAND DOMAIN=""example.com" BRAND_CODE="mycoolbrand"
Prerequisites Company-level permissions.
Required • DOMAINDomain name. must already exist
NOTE You must specify at least one of the optional attributes.
Optional • BRANDThe brand associated with this domain.
• BRAND_CODEName of the brand as it appears in the MAC or is returned by GET_DOMAIN_BRAND
Returns When the command is issued correctly, APP returns the following message:OK 0
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• ER 52 Brand Code not found
Chapter 3 APP Commands Domain commands 29
Account Provisioning ProtocolDeveloper’s Guide
SET_DOMAIN_CATCH_ALL_MAILBOX
Syntax SET_DOMAIN_CATCH_ALL_MAILBOX DOMAIN="<domain>" [MAILBOX="<mailbox>"][STATE="T"]
IMPORTANT SET_DOMAIN_CATCH_ALL_MAILBOX has been deprecated. You can no longer set catchall mailboxes.
Description Sets the domain catch-all mailbox, which receives any mail sent to a nonexistent mailbox in the domain. This prevents mail from bouncing. The catch-all mailbox must be a mailbox within the domain. For example:SET_DOMAIN_CATCH_ALL_MAILBOX DOMAIN="example.com"
MAILBOX="default"STATE="T"
You must set STATE as “T” to enable the mailbox. Setting only MAILBOX and DOMAIN specifies a pre-existing mailbox as a catch-all mailbox, but does not activate it.
NOTE We do not retain the value of the catchall mailbox when catchall is disabled.
Prerequisites Domain-level permissions.
Required • DOMAIN
• STATET turns the feature on and F turns it off.
• MAILBOXThe mailbox to be made a catch-all.
NOTE MAILBOX is required only when enabling.
Optional None
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is one of type: alias, or forward_only)
• 20 Invalid catch-all state (you tried to set STATE=”T” without specifying a value for MAILBOX)
Chapter 3 APP Commands Domain commands 30
Account Provisioning ProtocolDeveloper’s Guide
SET_DOMAIN_DISABLED_STATUS
Syntax SET_DOMAIN_DISABLED_STATUS DOMAIN="<domain>"
Description Enables or disables the specified domain. For example:
SET_DOMAIN_DISABLED_STATUS DOMAIN="example.com" DISABLED="T"
NOTE This command can only executed by Company Admins and higher. A domain disabled by a Super Admin cannot not be enabled by a Company Admin
Prerequisites Company-level permissions.
Required • DOMAIN
• DISABLEDT disables the domain and F enables it.
Optional None
Returns When the command is issued correctly, APP returns the following message:OK 0 success
Errors
GET_NUM_DOMAIN_MAILBOXES
Syntax GET_NUM_DOMAIN_MAILBOXES DOMAIN="<domain>"
Description Gets the number of mailboxes in a domain and displays by mailbox type. For example:
GET_NUM_DOMAIN_MAILBOXES DOMAIN="example.com"
Prerequisites Domain-level permissions.
Required DOMAIN
Optional None
Chapter 3 APP Commands Domain commands 31
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:In version 3.4:
OK 0NORMAL="2" GROUP_ALIAS="0 ALIAS=”0” FORWARD_ONLY="0" POPLINK="0" DOMAIN_CATCH_ALL="F"
In version 3.5 and later:
OK 0MAILBOX="2" ALIAS="0 FORWARD="0" FILTER="" DOMAIN_CATCH_ALL="F"
Errors 10 Nonexistent domain (only in version 3.5 and earlier)
GET_DOMAIN_MAILBOXES
Syntax GET_DOMAIN_MAILBOXES DOMAIN="<domain>"[LIMIT="<n>"]
Description Returns a list of all mailbox names in the domain, along with their types and workgroup names. For example:
GET_DOMAIN_MAILBOXES DOMAIN="example.com" LIMIT="1000"
Prerequisites Domain-level permissions
Required • DOMAIN
Optional • LIMITSets the maximum number of mailboxes the command will return. The default limit is 100,000 (mailboxes), which can be set lower. Use a lower number to speed up the command's processing; the more mailboxes the command needs to return, the longer it will take to return the results.
NOTE If you specify LIMIT as over 100K, the command ignores the request and instead uses the default of 100K, but returns no error. Administrators can set LIMIT to be higher than the default.
GET_NUM_DOMAIN_MAILBOXES
Chapter 3 APP Commands Domain commands 32
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:In version 3.4:
OK 0MAILBOX TYPE WORKGROUP"mb1" "NORMAL" "staff","mb2" "OTHER" "staff","mb3" "NORMAL" "staff"
In version 3.5 and later:
OK 0 SuccessMAILBOX,TYPE,WORKGROUP,ALIAS TARGET,FORWARD_RECIPIENT,FORWARD_RECIPIENT_COUNT"1","mailbox","994","","","""24nospam","mailbox","staff","","","""w4","forward","fo","","[email protected]","1""second1","alias","unknown","[email protected]","","""a16","mailbox","staff","","","2"
NOTE In version 3.5 and later, f FORWARD_RECIPIENT_COUNT >1, then FORWARD_RECIPIENT is not displayed.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 1 Syntax error (LIMIT is negative or non-numeric)
• 46 Domain has too many mailboxes (Number of mailboxes to be returned is over the specified LIMIT)
GET_DOMAIN_MAILBOX_LIMITS
Syntax GET_DOMAIN_MAILBOX_LIMITS DOMAIN="<domain>"
Description Returns the limits for each mailbox type. For example:
GET_DOMAIN_MAILBOX_LIMITS DOMAIN="example.com"
Prerequisites Domain-level permissions.
Required DOMAIN
Optional None
GET_DOMAIN_MAILBOXES
Chapter 3 APP Commands Domain commands 33
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:In version 3.4:
OK 0 SuccessMAILBOX="500" FILTER_ONLY="500" ALIAS="600" FORWARD_ONLY="500" MAILING_LIST="500"
Since the same limit applies to MAILBOX, FILTER_ONLY, FORWARD_ONLY, and MAILING_LIST, each of these values will be the same, and will be the largest of the values set using SET_DOMAIN_MAILBOX_LIMITS.
In version 3.5 and later:
OK 0 SuccessUSER="500" ALIAS="600"
In version 3.5 and later, the command returns only USER and ALIAS limits and the value of ALIAS is the largest of the values.
Errors
SET_DOMAIN_MAILBOX_LIMITS
Syntax SET_DOMAIN_MAILBOX_LIMITS DOMAIN="<domain>"
Description Sets the number of each mailbox type that can be created. For example:
SET_DOMAIN_MAILBOX_LIMITS DOMAIN="example.com" MAILBOX="500" FILTER_ONLY="150"
Prerequisites Company Admins and higher
Required DOMAIN
GET_DOMAIN_MAILBOX_LIMITS
Chapter 3 APP Commands Domain commands 34
Account Provisioning ProtocolDeveloper’s Guide
Optional • MAILBOXIn version 3.4.
• FILTER_ONLYIn version 3.4.
• ALIASThe number of aliases that can be created.
• FORWARD_ONLYIn version 3.4.
• MAILING_LISTIn version 3.4.
• USERIn version 3.5 and later. The largest of the values set for MAILBOX, FILTER_ONLY, FORWARD_ONLY, and MAILING_LIST
Returns When the command is issued correctly, APP returns the following message:In version 3.4:
OK 0 SuccessMAILBOX="500" FILTER_ONLY="500" ALIAS="600" FORWARD_ONLY="500" MAILING_LIST="500"
Since the same limit applies to MAILBOX, FILTER_ONLY, FORWARD_ONLY, and MAILING_LIST, each of these values will be the same, and will be the largest of the values set using SET_DOMAIN_MAILBOX_LIMITS.
In version 3.5 and later:
OK 0 SuccessUSER="500" ALIAS="600"
In version 3.5 and later, the command returns only USER and ALIAS limits and the value of USER is the largest of the values set for MAILBOX, FILTER_ONLY, FORWARD_ONLY, and MAILING_LIST.
Errors
SET_DOMAIN_MAILBOX_LIMITS
Chapter 3 APP Commands Domain commands 35
Account Provisioning ProtocolDeveloper’s Guide
SET_DOMAIN_ALLOW_LIST
Syntax SET_DOMAIN_ALLOW_LIST DOMAIN="<domain>"LIST="[email protected]*domain.tld"
Description Creates a new Allow Sender List for the domain.
WARNING Any previously existing Allow Sender List for the domain will be overwritten without notification.
Prerequisites Domain level permissions.
Required • DOMAIN
• LISTMaximum 1000 entries.
NOTE Domains entered in the LIST attribute require an asterisk (*) as illustrated above in the syntax example. The LIST is \n separated.
Asterisk (*) is the only allowed wildcard. Multiple asterisks are accepted.
Optional None
Returns When the command is issued correctly, APP returns the following message:OK 0
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
SET_DOMAIN_BLOCK_LIST
Syntax SET_DOMAIN_BLOCK_LIST DOMAIN="<domain>"LIST="[email protected]*domain.tld"
Description Creates a new Block Sender List for the domain.
WARNING Any previously existing Block Sender List for the domain will be overwritten without notification.
Prerequisites Domain level permissions.
Chapter 3 APP Commands Domain commands 36
Account Provisioning ProtocolDeveloper’s Guide
Required • DOMAIN
• LISTMaximum 1000 entries.
NOTE Domains entered in the LIST attribute require an asterisk (*) as illustrated above in the syntax example. The LIST is \n separated.
Asterisk (*) is the only allowed wildcard. Multiple asterisks are accepted.
Optional None
Returns When the command is issued correctly, APP returns the following message:OK 0
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
GET_DOMAIN_ALLOW_LIST
Syntax GET_DOMAIN_ALLOW_LIST DOMAIN="<domain>"
Description Returns the Allow Sender List for the domain.
Prerequisites Domain level permissions.
Required • DOMAIN
Optional None
Returns When the command is issued correctly, APP returns the following message:OK 0List="[email protected]“yahoo.com"
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
SET_DOMAIN_BLOCK_LIST
Chapter 3 APP Commands Domain commands 37
Account Provisioning ProtocolDeveloper’s Guide
GET_DOMAIN_BLOCK_LIST
Syntax GET_DOMAIN_BLOCK_LIST DOMAIN="<domain>"
Description Returns the Block Sender List for the domain.
Prerequisites Domain level permissions.
Required • DOMAIN
Optional None
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
Chapter 3 APP Commands Domain commands 38
Account Provisioning ProtocolDeveloper’s Guide
Workgroup commands
CREATE_WORKGROUP
Syntax CREATE_WORKGROUP WORKGROUP="<group>" DOMAIN="<domain>"
Description Creates a workgroup within the specified domain. For example:
CREATE_WORKGROUP WORKGROUP="db-techies" DOMAIN="example.com"
Prerequisites Domain level permission
Required • WORKGROUP
• DOMAIN
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0 Workgroup created.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 11 Invalid workgroup name syntax
• 12 Workgroup already exists
GET_DOMAIN_WORKGROUPS
Syntax GET_DOMAIN_WORKGROUPS DOMAIN="<domain>" [LIMIT=”<x>”]
Description Returns a list of workgroups in the specified domain. For example:
GET_DOMAIN_WORKGROUPS DOMAIN="example.com" LIMIT=”50”
Prerequisites Domain-level permissions.
Required • DOMAINMust be an existing domain.
Optional • LIMITRestricts the number of workgroups returned; the default is 100,000. If you specify a number greater than 100,000, the number is ignored, and the default value of 100,000 is used. LIMIT must be a positive integer..
Chapter 3 APP Commands Workgroup commands 39
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:In version 3.4:
OK 0WORKGROUP CREATE_DATE
"staff" "01/01/2004","test1" "01/01/2004"
NOTE The CREATE_DATE value is always listed as 01/01/2004.
In version 3.5 and later:
OK 0 SuccessWORKGROUP,MAILBOX_COUNT,FORWARD_COUNT,ALIAS_COUNT"994","11","3","5","0""blob","0","0","0","0""bubba","0","0","0","0"
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 46 Domain has too many workgroups
DELETE_WORKGROUP
Syntax DELETE_WORKGROUP WORKGROUP="<group>" DOMAIN="<domain>"[CASCADE="T|F"]
Description Removes a workgroup from the specified domain. For example:
DELETE_WORKGROUP WORKGROUP="db-techies" DOMAIN="example.com"
CASCADE="T"
Prerequisites Domain-level permissions.
Required • WORKGROUPWorkgroup name.
• DOMAINDomain name.
GET_DOMAIN_WORKGROUPS
Chapter 3 APP Commands Workgroup commands 40
Account Provisioning ProtocolDeveloper’s Guide
Optional • CASCADEBoolean T or F, F by default. When set to T, enables the command to delete all mailboxes in the domain, if any exist. If the workgroup has more than a specified number of mailboxes, the command displays error 28 and deletes nothing.
• LIMITOverrides the default limit. Specify the maximum number of mailboxes.
Returns When the command is issued correctly, APP returns the following message:OK 0 Workgroup deleted.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 13 Nonexistent workgroup
• 28 Too many mailboxes for cascade delete (current mailbox count > current limit)
SET_WORKGROUP_ADMIN
Syntax SET_WORKGROUP_ADMIN DOMAIN="<domain>" MAILBOX="<mailbox>" [STATE="T|F"]
Description Grants or removes administration privileges over the workgroup to which the mailbox already belongs. For example:
SET_WORKGROUP_ADMIN DOMAIN="example.com" MAILBOX="db-admin"STATE="T"
If adding administrator privileges, this command attempts to remove any other administrator privileges (Company, Domain) the mailbox already has and fails if the caller has insufficient permission to do so. If removing privileges, this command returns OK 0 if the mailbox did not have Workgroup administrator in the first place.
Prerequisites Domain-level permissions.
Required • DOMAIN
• MAILBOX
Optional • STATEBoolean T or F. T means grant Workgroup administration privileges (default), while F means remove privileges.
DELETE_WORKGROUP
Chapter 3 APP Commands Workgroup commands 41
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:OK 0
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox or
• 17 Invalid mailbox type (if mailbox is one of type: alias or forward_only)
SET_WORKGROUP_ADMIN
Chapter 3 APP Commands Workgroup commands 42
Account Provisioning ProtocolDeveloper’s Guide
Mailbox commands
General
GET_MAILBOX_AVAILABILITY
Syntax GET_MAILBOX_AVAILABILITY DOMAIN="<domain>" MAILBOX_LIST="<mailbox1,mailbox2,...mailboxN>"
Description Takes a list of mailbox names in a domain and returns whether or not they exist. For example:
GET_MAILBOX_AVAILABILITY DOMAIN="example.com" MAILBOX_LIST="joe,rsmith,janew"
Prerequisites Domain-level permissions.
Required • DOMAINDomain name.
• MAILBOX_LISTComma=delimited list of mailbox names.
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0 SuccessAVAILABLE_LIST="T,T,F"
AVAILABLE_LIST indicates whether each mailbox listed in the request exists. "T" indicates that the mailbox exists.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
Chapter 3 APP Commands Mailbox commands 43
Account Provisioning ProtocolDeveloper’s Guide
GET_ALTERNATE_MAILBOX_NAMES
Syntax GET_ALTERNATE_MAILBOX_NAMES MAILBOX_LIST="<mailbox1,mailbox2,...mailboxN>"
Description Given a comma-delimited list of mailbox names (in the form mailbox@domain), returns the same list with alternate suggestions for those which are already taken. For example:
GET_ALTERNATE_MAILBOX_NAMES MAILBOX_LIST="[email protected],[email protected]"
Use this command as an alternative to the command GET_MAILBOX_AVAILABILITY.
Prerequisites None
Required • MAILBOX_LISTCandidate mailbox names.
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0MAILBOX_LIST="[email protected],[email protected]"
Errors An invalid mailbox in the list will be replaced with “*nodomain*”
Chapter 3 APP Commands Mailbox commands 44
Account Provisioning ProtocolDeveloper’s Guide
CREATE_MAILBOX
Syntax CREATE_MAILBOX DOMAIN="<domain>" WORKGROUP="<group>"MAILBOX="<name>"PASSWORD="<pwd>"[FIRST_NAME="<first>"][LAST_NAME="<last>"][TITLE="<title>"][PHONE="<phone_number>"][FAX="<fax_number>"][TIMEZONE="<zone>"][LANGUAGE="<language>"][FILTERONLY="T|F"][SPAM_TAG="<tag>"][SPAM_FOLDER="<folder>"][SPAM_LEVEL="<level>"]
NOTE SPAM_TAG and SPAM_FOLDER are not supported when creating a filteronly mailbox.
Description Adds a new mailbox to the specified domain. For example:CREATE_MAILBOX DOMAIN="example.com" WORKGROUP="staff"
MAILBOX="ken" PASSWORD="s0up@K" FIRST_NAME="first"LAST_NAME="last"TITLE="title"PHONE="+1 415 555 1212"TIMEZONE=”Europe/Amsterdam”LANGUAGE="en"
Prerequisites Workgroup level permission
Required • MAILBOXMust not already exist in DOMAIN.
• PASSWORDMust consist entirely of printable, non-space characters. For guidelines on creating passwords, see “User name and password rules” on page 103.
• WORKGROUPMust exist in DOMAIN.
• DOMAIN
Chapter 3 APP Commands Mailbox commands 45
Account Provisioning ProtocolDeveloper’s Guide
Optional • FILTERONLYMust be T in order to create a filter-only or “spam quarantine” mailbox.
• FIRST_NAMEMailbox user’s first name.
• LAST_NAMEMailbox user’s last name.
• PHONEMailbox user’s phone number.
• FAX
Mailbox user’s fax number; can be a maximum of 30 characters.• TITLE
Mailbox user’s job title.
• TIMEZONEMailbox user's time zone. See Appendix 4, “Timezone values.”
• LANGUAGEMailbox user’s preferred language. Valid values are as follows: da, en, es, de, fr, it, nl, no, pt_BR, and sv.
• SPAM_TAGThe value of this field will be appended to the subject of any message identified as spam. Max. 30 char.This is not supported for filteronly accounts.
• SPAM_FOLDERSpecifies the folder into which spam will be delivered for the mailbox with the following parameters: argument max length is 128 characters and should take the form of a dot separated folder path; individual folders cannot exceed 30 characters.This is not supported for filteronly accounts.
• SPAM_LEVELThe agressiveness level of spam filtering. Valid values are NORMAL, HIGH, VERY HIGH, and ""(none). When set to NORMAL, most spam is caught. When set to HIGH or VERY HIGH, more spam is caught, but the likelihood that non-spam messages (false positives) will be labelled as spam increases accordingly. If this value is not set, the mailbox uses the SPAM_LEVEL setting for the next highest level (for example, domain or company).
NOTE For guidelines on defining the MAILBOX, PASSWORD, FIRST_NAME, and LAST_NAME attributes, see “User name and password rules” on page 103.
CREATE_MAILBOX
Chapter 3 APP Commands Mailbox commands 46
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox created.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 13 Nonexistent workgroup
• 14 Invalid mailbox name syntax
• 15 Invalid password syntax. Password must contain only alpha, numeric, alphanumeric and ~!@#$%^&'*() _=+/*\][{}:;><,.`|?
• 15 Invalid password syntax. Password must not be empty.
• 15 Invalid password syntax. Password must not be more than 54 characters long.
• 16 Mailbox already exists
• 111 Invalid SPAM_LEVEL
• 112 Maximum number jof mailboxes of this type for this domain reached
SET_MAIL_ADMIN
Syntax SET_MAIL_ADMIN DOMAIN="<domain>"MAILBOX="<mailbox>"[STATE="T|F"]
Description Grants or removes administration privileges to view and change mailboxes. For example:
SET_MAIL_ADMIN DOMAIN="example.com" MAILBOX="foo" STATE="T"
Prerequisites Domain-level permissions.
Required • DOMAIN
• MAILBOX
Optional • STATEBoolean T or F. The default is T.
CREATE_MAILBOX
Chapter 3 APP Commands Mailbox commands 47
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:OK 0
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is one of type: alias or forward_only)
CHANGE_MAILBOX
Syntax CHANGE MAILBOX DOMAIN="<domain>" MAILBOX="<mailbox>"[WORKGROUP="<group>"][PASSWORD="<pwd>"][FIRST_NAME="<first>"][LAST_NAME="<last>"][TITLE="<title>"][PHONE="<number>"][FAX="<fax_number>"][NEW_MAILBOX_NAME="<mailbox>"][TIMEZONE="<zone>"][LANGUAGE="<language>"][FILTERONLY="T|F"][SPAM_TAG="<tag>"][SPAM_FOLDER="<folder>"][SPAM_LEVEL="<level>"]
SET_MAIL_ADMIN
Chapter 3 APP Commands Mailbox commands 48
Account Provisioning ProtocolDeveloper’s Guide
Description Changes the mailbox attributes listed below. For example:CHANGE MAILBOX DOMAIN="example.com" MAILBOX="kenny"
WORKGROUP="staff"PASSWORD="s0upKa"FIRST_NAME="Ken"LAST_NAME="Dryden"TITLE="Legal Counsel"PHONE="+1 415 555 1212"NEW_MAILBOX_NAME="newkenny"TIMEZONE="Europe/Amsterdam"LANGUAGE="en"FILTERONLY="T"
If you specify a different domain, it creates the mailbox in that domain. If the domain is not specified, the new mailbox is created in the same domain as the old one. For example:
CHANGE_MAILBOX DOMAIN="example.com" MAILBOX="rigby" NEW_MAILBOX_NAME="[email protected]"
This example renames [email protected] to [email protected].
NOTE Only mailboxes, forwards, and filters can be renamed.
Prerequisites Mailbox level permissions
Required • MAILBOXThe current name of the mailbox. Can be used with NEW_MAILBOX_NAME when you want to rename the mailbox.
• DOMAINDomain name.
NOTE At least one optional attribute must be set.
CHANGE_MAILBOX
Chapter 3 APP Commands Mailbox commands 49
Account Provisioning ProtocolDeveloper’s Guide
Optional • PASSWORDMust consist entirely of printable, non-space characters. For guidelines on creating passwords, see “User name and password rules” on page 103.
• FIRST_NAMEMailbox user’s first name.
• LAST_NAMEMailbox user’s last name.
• PHONEMailbox user’s phone number.
• FAX
Mailbox user’s fax number; can be a maximum of 30 characters.• TITLE
Mailbox user’s job title.
• WORKGROUPAdds a new workgroup for the specified mailbox; must be a valid workgroup in DOMAIN.
• NEW_MAILBOX_NAMEThe new name for the mailbox. Can be used with MAILBOX when you want to rename the mailbox.
• TIMEZONEMailbox user's time zone. See Appendix 4, “Timezone values.”
• LANGUAGE
• Mailbox user’s language. Valid values are as follows: da, en, es, de, fr, it, nl, no, pt_BR, and sv.
• FILTERONLYSet the FILTERONLY value to F to change a filter-only mailbox to a regular mailbox.
• SPAM_TAGThe value of this field will be appended to the subject of any message identified as spam. To remove an existing tag, as opposed to overwriting it, leave the value empty (i.e., SPAM_TAG=" "). Max. 30 char.
• SPAM_FOLDERSpecifies the folder into which spam will be delivered for the mailbox with the following parameters: argument max length is 128 characters and should take the form of a dot separated folder path; individual folders cannot exceed 30 characters.
CHANGE_MAILBOX
Chapter 3 APP Commands Mailbox commands 50
Account Provisioning ProtocolDeveloper’s Guide
• SPAM_LEVELThe agressiveness level of spam filtering. Valid values are NORMAL, HIGH, VERY HIGH, and "" (none). When set to NORMAL, most spam is caught. When set to HIGH or VERY HIGH, more spam is caught, but the likelihood that non-spam messages (false positives) will be labelled as spam increases accordingly. If this value is not set, the mailbox uses the SPAM_LEVEL setting for the next highest level (for example, domain or company).
NOTE For guidelines on defining the MAILBOX, PASSWORD, FIRST_NAME, and LAST_NAME attributes, see “User name and password rules” on page 103.
Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox changed.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 13 Nonexistent workgroup
• 14 Invalid mailbox name syntax. Mailbox name does not comply with RFC conventions
• 15 Invalid password syntax. Password must contain only alpha, numeric, alphanumeric and ~!@#$%^&'*() _=+/*\][{}:;><,.`|?
• 15 Invalid password syntax. Password must not be empty.
• 15 Invalid password syntax. Password must not be more than 54 characters long.
• 17 Nonexistent mailbox17 Invalid mailbox type (if mailbox is one of type: alias or forward_only)
• 111 Invalid SPAM_LEVEL
• 200 Problem in moving mailbox to workgroup
• 207 Invalid Timezone value
CHANGE_MAILBOX
Chapter 3 APP Commands Mailbox commands 51
Account Provisioning ProtocolDeveloper’s Guide
CREATE_ALIAS_MAILBOX
Syntax CREATE_ALIAS_MAILBOX ALIAS_MAILBOX="<mailbox>"MAILBOX="<mailbox>"DOMAIN="<domain>"
Description Creates a nickname—a mailbox name that points to an existing mailbox. For example:CREATE_ALIAS_MAILBOX ALIAS_MAILBOX="jon"
MAILBOX="jonathan"DOMAIN="example.com"
To create an intra-domain mailbox alias, specify the full email address
Prerequisites Workgroup level permissions
Required • MAILBOXA normal user mailbox that exists in the specified domain
• DOMAINA domain that already exists on the system
• ALIAS_MAILBOXAlias name that points to MAILBOX; must be a new mailbox name that doesn’t already exist in the domain. To create an intra-domain mailbox alias, specify the full email address instead of the username.
Optional None
Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox created.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 14 Invalid mailbox name syntax
• 16 Mailbox already exists
• 17 Nonexistent mailbox
• 112 Maximum number of mailboxes of this type for this domain reached
Chapter 3 APP Commands Mailbox commands 52
Account Provisioning ProtocolDeveloper’s Guide
RENAME_MAILBOX
Syntax RENAME_MAILBOX DOMAIN="<domain>" OLD_MAILBOX="<mailbox>" NEW_MAILBOX="<mailbox>"
Description Renames a mailbox and moves all of the mailbox's settings, folders, and aliases to the new name, leaving the old name unused. If you specify a different domain, it creates the mailbox in that domain. If the domain is not specified, the new mailbox is created in the same domain as the old one. For example:
RENAME_MAILBOX DOMAIN="example.com" OLD_MAILBOX="rigby" NEW_MAILBOX="[email protected]"
This example renames [email protected] to [email protected].
NOTE Only mailboxes, forwards, and filters can be renamed.
Prerequisites Workgroup-level permissions or higher.
Required • DOMAIN
• OLD_MAILBOX
• NEW_MAILBOX
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox renamed.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (OLD_MAILBOX isn't a regular user mailbox)
• 14 Invalid mailbox name syntax (NEW_MAILBOX is invalid mailbox)
• 16 Mailbox already exists (NEW_MAILBOX already exists)
• 35 Mailbox has calendaring (a mailbox that has calendaring enabled cannot be renamed)
Chapter 3 APP Commands Mailbox commands 53
Account Provisioning ProtocolDeveloper’s Guide
SET_MAILBOX_ALLOW_LIST
Syntax SET_MAILBOX_ALLOW_LIST DOMAIN="<domain>"MAILBOX="<mailbox>"LIST="*@[email protected]*domain.tld"
Description Creates a new Allow Sender List for the mailbox.
WARNING Any previously existing Allow Sender List for the mailbox will be overwritten without notification.
Prerequisites Mailbox level permissions.
Required • MAILBOX
• DOMAIN
• LISTMaximum 1000 entries.
NOTE Domains entered in the LIST attribute require an asterisk (*) as illustrated above in the syntax example. The LIST is \n separated.
Asterisk (*) is the only allowed wildcard. Multiple asterisks are accepted.
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
Chapter 3 APP Commands Mailbox commands 54
Account Provisioning ProtocolDeveloper’s Guide
SET_MAILBOX_BLOCK_LIST
Syntax SET_MAILBOX_BLOCK_LIST DOMAIN="<domain>"MAILBOX="<mailbox>"LIST="*@[email protected]*domain.tld"
Description Creates a new Block Sender List for the mailbox.
WARNING Any previously existing Block Sender List for the mailbox will be overwritten without notification.
Prerequisites Mailbox level permissions.
Required • MAILBOX
• DOMAIN
• LISTMaximum 1000 entries.
NOTE Domains entered in the LIST attribute require an asterisk (*) as illustrated above in the syntax example. The LIST is \n separated.
Asterisk (*) is the only allowed wildcard. Multiple asterisks are accepted.
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
Chapter 3 APP Commands Mailbox commands 55
Account Provisioning ProtocolDeveloper’s Guide
GET_MAILBOX_ALLOW_LIST
Syntax GET_MAILBOX_ALLOW_LIST DOMAIN="<domain>"MAILBOX="<mailbox>"
Description Returns the Allow Sender List for the mailbox.
Prerequisites Mailbox level permissions.
Required • MAILBOX
• DOMAIN
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0 SuccessLIST="*@[email protected]*tucows.com"
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
Chapter 3 APP Commands Mailbox commands 56
Account Provisioning ProtocolDeveloper’s Guide
GET_MAILBOX_BLOCK_LIST
Syntax GET_MAILBOX_BLOCK_LIST DOMAIN="<domain>" MAILBOX="<mailbox>"
Description Returns the Block Sender List for the mailbox.
Prerequisites Mailbox level permissions.
Required • MAILBOX
• DOMAIN
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0 SuccessLIST="*@[email protected]*tucows.com"
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
VERIFY_PASSWORD
Syntax VERIFY_PASSWORD DOMAIN="<domain>"MAILBOX="<mailbox>"PASSWORD="<pwd>"
Description Verify mailbox account password. For example:
VERIFY_PASSWORD DOMAIN="example.com"MAILBOX="sam75"PASSWORD="45erklcv"
Prerequisite Mailbox-level permissions or higher
Chapter 3 APP Commands Mailbox commands 57
Account Provisioning ProtocolDeveloper’s Guide
Required • DOMAINDomain name.
• MAILBOXMailbox name.
• PASSWORDMailbox password.
Returns When the command is issued correctly, APP returns the following message:OK 0 successVALID="T|F"
• VALID“T” or “F” to indicate whether the specified password is valid for the specified mailbox.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
GET_ADMIN
Syntax GET_ADMIN DOMAIN="<domain>" MAILBOX="<mailbox>"
Description Returns the administrator level of the specified mailbox. For example:
GET_ADMIN DOMAIN="example.com" MAILBOX="schlepp"
Prerequisites None
Required • DOMAIN
• MAILBOX
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0LEVEL="<admin_level>"
Where admin_level will be one of: Company, Domain, Mail, or Workgroup.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is one of type: alias or forward_only)
VERIFY_PASSWORD
Chapter 3 APP Commands Mailbox commands 58
Account Provisioning ProtocolDeveloper’s Guide
GET_MAILBOX
Syntax GET_MAILBOX DOMAIN="<domain>" MAILBOX="<mailbox>"
Description Returns mailbox attributes for regular and filter-only mailboxes. For example:
GET_MAILBOX DOMAIN="example.com" MAILBOX="joe"
Prerequisites Mailbox level permissions
Required • DOMAINA domain that already exists on the system
• MAILBOXA normal user mailbox that exists within the specified domain
Chapter 3 APP Commands Mailbox commands 59
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:In version 3.4:
OK 0 SuccessFIRST_NAME="John" LAST_NAME="Doe" PHONE="+1 415 555 1212" FAX="" TITLE="title" DOMAIN="example.com" BRAND="" MAILBOX="jdoe" PASSWORD="{MD5}$1$tmaszffk$Ux17X5qnkjXT/vSH0xmRl0" TIMEZONE="America/Montreal" LANGUAGE="en" FILTERONLY="F" SPAM_TAG=”” SPAM_FOLDER=”” SPAM_LEVEL="NORMAL"
In version 3.5 and later:
OK 0 SuccessFIRST_NAME="John" LAST_NAME="Doe" PHONE="+1 415 555 1212" FAX="" TITLE="title" DOMAIN="example.com" BRAND="" MAILBOX="jdoe" PASSWORD="{MD5}$1$tmaszffk$Ux17X5qnkjXT/vSH0xmRl0" TIMEZONE="America/Montreal" LANGUAGE="en" FILTERONLY="F" ALIAS_TO=”[email protected]_TYPE=”mailbox” TYPE=”alias”SPAM_TAG=”” SPAM_FOLDER=”” SPAM_LEVEL="NORMAL"FORWARD_RECIPIENTS="[email protected],[email protected]"LOCAL_DELIVERY="T"FORWARD_DELIVERY="F" AUTORESPOND_DELIVERY="F" AUTORESPOND_TEXT="some vacation msg" AUTORESPOND_INTERVAL="1" AUTORESPOND_ENDDATE="2011-12-31 23:59:59 ALLOW="allow2allow1" BLOCK="block1 block34"
• FIRST_NAMEMailbox user’s first name.
• LAST_NAMEMailbox user’s last name.
GET_MAILBOX
Chapter 3 APP Commands Mailbox commands 60
Account Provisioning ProtocolDeveloper’s Guide
• TITLEMailbox user’s job title.
• PHONEMailbox user’s phone number.
• FAX
Mailbox user’s fax number.• DOMAIN
The domain to which the mailbox belongs.
• BRANDThe brand associated with this domain.
• MAILBOXMailbox name.
• FILTERONLY“T” or “F” to indicate whether the mailbox is a filter-only or Spam Quarantine account.
• PASSWORDPassword for this mailbox.
• TIMEZONETime zone for this mailbox. See Appendix 4, “Timezone values.”
• LANGUAGELanguage for this mailbox. Valid values are as follows: da, en, es, de, fr, it, nl, no, pt_BR, and sv.
• SPAM_TAGA text tag appended to any the subject of any messages identified as spam. Empty if no tag is specified. Max. 30 char.
GET_MAILBOX
Chapter 3 APP Commands Mailbox commands 61
Account Provisioning ProtocolDeveloper’s Guide
• SPAM_FOLDERThe folder to which messages identified as spam are delivered. This value will be empty if no folder has been specified. However, the system default of Spam will be applied to the domain and inherited by the mailbox. Max. 30 char.
• SPAM_LEVELThe agressiveness level of spam filtering. Valid values are NORMAL, HIGH, VERY HIGH, and "" (none).
• TYPEAvailable in version 3.5 and later. The mailbox type: MAILBOX, FILTER, FORWARD, or ALIAS.
• ALIAS_TOAvailable in version 3.5 and later. The address that is an alias of this mailbox. Returned if TYPE = alias
• ALIAS_TYPEAvailable in version 3.5 and later. The type of account that is used as an alias. Returned if TYPE = alias.
• FORWARD_RECIPIENTSAvailable in version 3.5 and later.The recipients to whom messages to this mailbox are forwarded.
• LOCAL_DELIVERYAvailable in version 3.5 and later. “T” or “F” to indicate whether a copy of the message is saved locally.
• FORWARD_DELIVERYAvailable in version 3.5 and later. “T” or “F” to indicate whether forwarding is enabled.
• AUTORESPOND_DELIVERYAvailable in version 3.5 and later. “T” or “F” to indicate whether autoresponses are generated when new mail arrives.
• AUTORESPOND_TEXTAvailable in version 3.5 and later.The text of the autoresponder message.
• AUTORESPOND_INTERVALAvailable in version 3.5 and later. The number of days before the same reciptient will receive the autoresponse message again.
• AUTORESPOND_ENDDATEAvailable in version 3.5 and later. The last day/time when the autoresponse message is in effect. The required format is YYYY-MM-DD hh:mm:ss
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is of type alias or forward_only)
GET_MAILBOX
Chapter 3 APP Commands Mailbox commands 62
Account Provisioning ProtocolDeveloper’s Guide
GET_MAILBOX_ANY
Syntax GET_MAILBOX_ANY DOMAIN="<domain>" MAILBOX="<mailbox>"
Description Returns attributes for any type of mailbox. For example:
GET_MAILBOX_ANY DOMAIN="example.com" MAILBOX="albatross"
Prerequisite Domain-level permissions or higher
Required • DOMAINDomain name.
• MAILBOXMailbox name.
Returns When the command is issued correctly, APP returns the following message:In version 3.4:
OK 0 SuccessMAILBOX="jdoe" DOMAIN="example.com" FIRST_NAME="John" LAST_NAME="Doe" PHONE="+1 415 555 1212" FAX="+1 416 555 1234"TITLE="title"PASSWORD="{MD5}$1$tmaszffk$Ux17X5qnkjXT/vSH0xmRl0"TIMEZONE="America/Montreal" LANG="fr"ALIAS_TO="" TYPE="Mailbox" SPAM_TAG="" SPAM_FOLDER="" SPAM_LEVEL="NORMAL" PROVISIONING_STATE="Completed"
In version 3.5 and later:
OK 0 SuccessDOMAIN="example.com" FIRST_NAME="John" LAST_NAME="Doe" PASSWORD="{MD5}$1$tmaszffk$Ux17X5qnkjXT/vSH0xmRl0" PHONE="+1 415 555 1212" FAX="" TITLE="title" PROVISIONING_STATE="Completed" MAILBOX="jdoe" TIMEZONE="America/Montreal" FILTERONLY="F" ALIAS_TO=”[email protected]_TYPE=”mailbox” TYPE=”alias”SPAM_TAG=”” SPAM_FOLDER=”” SPAM_LEVEL="NORMAL"FORWARD_RECIPIENTS="[email protected],[email protected]" LOCAL_DELIVERY="T"FORWARD_DELIVERY="F" AUTORESPOND_DELIVERY="F" AUTORESPOND_TEXT="some vacation msg" ALLOW="allos2allow1" BLOCK="block1 block34"
Chapter 3 APP Commands Mailbox commands 63
Account Provisioning ProtocolDeveloper’s Guide
• DOMAINDomain name.
• FIRST_NAMEMailbox user's first name.
• LAST_NAMEMailbox user's last name.
• MAILBOXThe mailbox account name.
• PASSWORDPassword associated with mailbox account.
• PHONEMailbox user's phone number.
• PROVISIONING_STATECurrent provisioning state of the mailbox (active or blocked).
• TIMEZONEMailbox user's time zone. See Appendix 4, “Timezone values.”
• TITLEMailbox user's title.
• TYPEThe mailbox type - Regular, Alias, Filter Only, Forward Only, or Mailing List.
• SPAM_TAGA text tag appended to any the subject of any messages identified as spam. Empty if no tag is specified or if the mailbox typeis Filter Only.
• SPAM_FOLDERThe folder to which messages identified as spam are delivered. This value will be empty if no folder has been specified or if the mailbox type is Filter Only.
• SPAM_LEVELThe agressiveness level of spam filtering. Valid values are NORMAL, HIGH, VERY HIGH, and "" (none).
• ALIAS_TOThe mailbox for which this mailbox is an alias. Empty if the mailbox is not an alias.
• ALIAS_TYPEAvailable in version 3.5 and later.The type of account that is used as an alias. Returned if TYPE = alias.
• FORWARD_RECIPIENTSThe recipients to whom messages to this mailbox are forwarded.
GET_MAILBOX_ANY
Chapter 3 APP Commands Mailbox commands 64
Account Provisioning ProtocolDeveloper’s Guide
• LOCAL_DELIVERYAvailable in version 3.5 and later“T” or “F” to indicate whether a copy of the message is saved locally.
• FORWARD_DELIVERYAvailable in version 3.5 and later. “T” or “F” to indicate whether forwarding is enabled.
• AUTORESPOND_DELIVERYAvailable in version 3.5 and later. “T” or “F” to indicatewhether autoresponses are generated when new mail arrives.
• AUTORESPOND_TEXTAvailable in version 3.5 and later. The text of the autoresponder message.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
GET_MAILBOX_ANY
Chapter 3 APP Commands Mailbox commands 65
Account Provisioning ProtocolDeveloper’s Guide
GET_MAILBOX_SERVICES
Syntax GET_MAILBOX_SERVICES DOMAIN="<domain>"MAILBOX="<mailbox>"
Description Returns the list of services for the specified mailbox and the state of each service. The service state may be enabled, disabled, or suspended.
NOTE We recommend that you use this command in place of the SHOW_AVAILABLE_OFFERINGS and SHOW_ENABLED_OFFERINGS commands.
Prerequisites Mailbox level permissions.
Required • MAILBOX
• DOMAIN
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0 SuccessPOP3="enabled" IMAP4="enabled" WEBMAIL="enabled" SMTPIN="suspended" SMTPRELAY="disabled" SMTPRELAY_WEBMAIL="enabled"
•
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
Chapter 3 APP Commands Mailbox commands 66
Account Provisioning ProtocolDeveloper’s Guide
SET_MAILBOX_SERVICES
Syntax SET_MAILBOX_SERVICES DOMAIN="<domain>"MAILBOX="<mailbox>" [POP3="state"] [IMAP4="state"]
[WEBMAIL="state"] [SMTPIN="state"] [SMTPRELAY="state"] [SMTPRELAY_WEBMAILL="state"]
Description Changes the state of one or more services for the specified mailbox. The state may be enabled, disabled, or suspended.
NOTE We recommend that you use this command in place of the DISABLE_OFFERING and ENABLE_OFFERING commands.
Prerequisites Mailbox level permissions.
Required • MAILBOX
• DOMAIN
Optional • POP3
• IMAP4
• WEBMAIL
• SMTPIN
• SMTPRELAY
• SMTPRELAY_WEBMAIL
NOTE You must specify at least one of these services.
Returns When the command is issued correctly, APP returns the following message:OK 0 Success
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
Chapter 3 APP Commands Mailbox commands 67
Account Provisioning ProtocolDeveloper’s Guide
GET_MAILBOX_QUOTA
Syntax GET_MAILBOX_QUOTA DOMAIN="<domain>"MAILBOX="<mailbox>"
Description Returns the quota (in MB) for the specified mailbox.
Prerequisites Mailbox level permissions.
Required • MAILBOX
• DOMAIN
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0 SuccessQUOTA="8192"
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
SET_MAILBOX_QUOTA
Syntax SET_MAILBOX_QUOTA DOMAIN="<domain>"MAILBOX="<mailbox>" QUOTA="8192"
Description Changes the quota (in MB) for the specified mailbox.
Prerequisites Mailbox level permissions.
Required • MAILBOX
• DOMAIN
• QUOTA
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0 Success
Errors • 2 Required attribute missing
• 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
Chapter 3 APP Commands Mailbox commands 68
Account Provisioning ProtocolDeveloper’s Guide
DELETE_MAILBOX
Syntax DELETE_MAILBOX MAILBOX="<mailbox>" DOMAIN="<domain>"
Description Removes a mailbox or filter only mailbox from the specified domain. For example:
DELETE_MAILBOX MAILBOX="kenny" DOMAIN="example.com"
Prerequisites Workgroup-level permissions.
Required • MAILBOXMailbox name.
• DOMAINDomain name.
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox Deleted
Errors • 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is one of type: alias or forward_only)
DELETE_MAILBOX_ANY
Syntax DELETE_MAILBOX_ANY DOMAIN="<domain>" MAILBOX="<mailbox>"
Description Deletes a mailbox, regardless of type (normal, filter only, alias, mailing list, or forward-only). For example:
DELETE_MAILBOX_ANY DOMAIN="example.com" MAILBOX="citybikers"
Prerequisites Workgroup level permissions
Required • DOMAIN
• MAILBOX
Optional None.
Chapter 3 APP Commands Mailbox commands 69
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox Deleted
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
DELETE_MAILBOX_ANY
Chapter 3 APP Commands Mailbox commands 70
Account Provisioning ProtocolDeveloper’s Guide
Options (Settings)
SET_MAILBOX_AUTORESPOND
Syntax SET_MAILBOX_AUTORESPOND MAILBOX="<mailbox>"DOMAIN="<domain>"[STATE="T|F"][TEXT="<text>"]
Description Sets the auto respond text and state for a given mailbox. For example:
SET_MAILBOX_AUTORESPOND MAILBOX="davidj" DOMAIN="example.com"
STATE="T"TEXT="Hi, I’m on tour for the next 3 months."INTERVAL="7"ENDDATE="2004-12-25 00:00:00"
Prerequisites Mailbox-level permissions.
Required • MAILBOXA normal user mailbox that exists in the specified domain.
• DOMAINA domain that already exists on the system.
IMPORTANT In addition to the required attributes, you must also specify either STATE or TEXT.
Optional • STATET turns the feature on and F turns it off.
• TEXTOutgoing message text.
• INTERVALThe number of days before the same recipient will receive the autoresponse again.
• ENDDATEThe last day/time when the autoresponse message is in effect. The required format is YYYY-MM-DD hh:mm:ss.
Returns When the command is issued correctly, APP returns the following message:OK 0 Success
Chapter 3 APP Commands Mailbox commands 71
Account Provisioning ProtocolDeveloper’s Guide
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is forward_only or alias)
• 185 The auto respond state should have either T or F
• 186 The auto respond interval should be a valid number.
• 187 Either auto respond text or auto respond state has to be specified.
• 188 Invalid auto respond end date. Format is YYYY-MM-DD hh:mm:ss, i.e. 2003-07-25 12:47:00
• 189 The auto respond date must not be before today's date.
• 208 Parameter auto_respond_text cannot be null or empty.
GET_MAILBOX_AUTORESPOND
Syntax GET_MAILBOX_AUTORESPOND DOMAIN="<domain>" MAILBOX="<mailbox>"
Description Gets the auto respond text and state (whether auto respond is active-T, or inactive-F) for a given mailbox. For example:
GET_MAILBOX_AUTORESPOND DOMAIN="example.com" MAILBOX="davidj"
Prerequisites None
Required • MAILBOXA normal user mailbox that exists within the specified domain.
• DOMAIN A domain that already exists on the system.
Optional None
SET_MAILBOX_AUTORESPOND
Chapter 3 APP Commands Mailbox commands 72
Account Provisioning ProtocolDeveloper’s Guide
Returned When the command is issued correctly, APP returns the following message:OK 0 SuccessMAILBOX="user1311616462698" DOMAIN="example.com" TEXT="This is a test" STATE="F" ENDDATE="9999-12-31 23:59:59" INTERVAL="1"
• DOMAINDomain name.
• MAILBOXName of mailbox.
• STATEWhether auto-respond is enabled ("T") or disabled ("F").
• TEXTAuto-respond text.
• INTERVALThe number of days before the same recipient will receive the autoresponse again.
• ENDDATEThe last day/time when the autoresponse message is in effect.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is forward_only or alias)
GET_MAILBOX_AUTORESPOND
Chapter 3 APP Commands Mailbox commands 73
Account Provisioning ProtocolDeveloper’s Guide
\
SET_MAILBOX_FORWARD
Syntax SET_MAILBOX_FORWARD MAILBOX="<mailbox>" DOMAIN="<domain>" [FORWARD="<email>"][KEEP_COPY="T|F"][STATE="T|F"]
Description Modifies the forwarding features of a mailbox. For example:
SET_MAILBOX_FORWARD MAILBOX="julie" DOMAIN="example.com" FORWARD="[email protected]"KEEP_COPY="T"STATE="T"
In this example, the mailbox [email protected] (where example.com is a domain hosted by OpenSRS) will be forwarded to the mailbox [email protected].
NOTE This command does not create a forward-only mailbox. See “CREATE_MAILBOX_FORWARD_ONLY” on page 88.
Prerequisites Mailbox level permissions
Required • MAILBOX
• DOMAIN
NOTE You must provide at least one optional attribute.
Optional • FORWARDAny valid email address, can be up to 2000 characters in length.
• KEEP_COPYT keeps a copy of incoming mail on the server and F does not.
• STATET turns the feature on and F turns it off.
Returns When the command is issued correctly, APP returns the following message:OK 0 Success
Chapter 3 APP Commands Mailbox commands 74
Account Provisioning ProtocolDeveloper’s Guide
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is forward_only or alias)
• 24 Invalid forward state
• 102 Invalid keep copy value
• 169 Forwarding e-mail address must be specified
NOTE This command doesn't return errors on non-existing or invalid mailboxes specified in FORWARD.
GET_MAILBOX_FORWARD
Syntax GET_MAILBOX_FORWARD DOMAIN="<domain>" MAILBOX="<mailbox>"
Description Returns information about the forward status of a regular mailbox or a forward-only mailbox. For example:
GET_MAILBOX_FORWARD DOMAIN="example.com" MAILBOX="sara"
Prerequisites Mailbox level permissions
Required • MAILBOXMAILBOX must exist in the specified DOMAIN.
• DOMAIN
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0FORWARD="[email protected]" KEEP_COPY="T" STATE="T"
In version 3.5 and later, KEEP_COPY always reflects whether the mailbox has local delivery enabled.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is alias)
SET_MAILBOX_FORWARD
Chapter 3 APP Commands Mailbox commands 75
Account Provisioning ProtocolDeveloper’s Guide
SHOW_AVAILABLE_OFFERINGS
Syntax SHOW_AVAILABLE_OFFERINGS DOMAIN="<domain>" MAILBOX="<mailbox>"
Description Shows what packages can be enabled for this mailbox. Omits currently enabled offerings (that is, includes offerings which were enabled, but have since been disabled or expired.) This means you can only have one instance of an offering active at any time. Displays everything in tabular format. For example:
SHOW_AVAILABLE_OFFERINGS DOMAIN="example.com" MAILBOX="foo"
Prerequisites Mailbox-level permissions.
Required • DOMAIN
• MAILBOX
Optional None
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is one of type: alias or forward_only)
SHOW_ENABLED_OFFERINGS
Syntax SHOW_ENABLED_OFFERINGS DOMAIN="<domain>"MAILBOX="<mailbox>"
Description Shows what packages (domain or company offerings) have already been enabled for a specific mailbox. Omits those which have since expired or been disabled. For example:
SHOW_ENABLED_OFFERINGS DOMAIN="example.com" MAILBOX="foo"
Effectively lists everything that can be disabled. Displays everything in tabular format.
Prerequisites Mailbox-level permissions.
Required • DOMAIN
• MAILBOX
Optional None
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is one of type: alias or forward_only)
Chapter 3 APP Commands Mailbox commands 76
Account Provisioning ProtocolDeveloper’s Guide
DISABLE_OFFERING
Syntax DISABLE_OFFERING MAILBOX_OFFERING_ID="<n>"
Description Disables a currently-enabled offering. For example:
DISABLE_OFFERING MAILBOX_OFFERING_ID="102"
Prerequisites Workgroup-level permissions.
Required • MAILBOX_OFFERING_IDLook up MAILBOX_OFFERING_ID on the list returned by SHOW_ENABLED_OFFERINGS. You don’t need to supply DOMAIN and MAILBOX, because the MAILBOX_OFFERING_ID is specific to a mailbox.
Optional None
Errors • 29 Offering not found
ENABLE_OFFERING
Syntax ENABLE_OFFERING DOMAIN="<domain>" MAILBOX="<mailbox>" OFFERING_ID="<n>" [AUTO_RENEW="T|F"]
Description Enables an available offering for a mailbox. For example:
ENABLE_OFFERING DOMAIN="example.com" MAILBOX="rex" OFFERING_ID="102" AUTO_RENEW="T"
Prerequisites Workgroup-level permissions.
Required • DOMAIN
• MAILBOX
• OFFERING_ID Find OFFERING_ID by looking on the list returned by the SHOW_AVAILABLE_OFFERINGS command.
Chapter 3 APP Commands Mailbox commands 77
Account Provisioning ProtocolDeveloper’s Guide
Optional • AUTO_RENEWA boolean which governs whether the offering should be automatically renewed upon expiration (defaults to “F”).
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox (or “invalid mailbox type” if mailbox is of type alias or forward_only)
• 29 Offering not found
ENABLE_OFFERING
Chapter 3 APP Commands Mailbox commands 78
Account Provisioning ProtocolDeveloper’s Guide
Suspension and resinstatement
SET_MAILBOX_SUSPENSION
Syntax SET_MAILBOX_SUSPENSIONMAILBOX="<name>"DOMAIN="<domain>"[SMTPIN="<T/F>"][SMTPRELAY="<T/F>"][SMTPRELAY_WEBMAIL="<T/F>"][IMAP="<T/F>"][POP="<T/F>"][WEBMAIL="<T/F>"]
Description Sets the suspended services for a mailbox.
NOTE We recommend that you use the newer command SET_MAILBOX_SERVICES instead.
T = suspend
Unspecified services default to 'F' (not suspended).
WARNING Any previously suspended service settings will be overwritten without notification.
Prerequisites Domain level permission.
Required • MAILBOX
• DOMAIN
Optional All other arguments are optional, therefore to reset all services to active status the command should be run with only the required arguments.
Returns When the command is issued correctly, APP returns the following message:OK 0
Errors • 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is forward-only or alias)
Chapter 3 APP Commands Mailbox commands 79
Account Provisioning ProtocolDeveloper’s Guide
GET_MAILBOX_SUSPENSION
Syntax GET_MAILBOX_SUSPENSIONMAILBOX="<name>"DOMAIN="<domain>"
Description Gets the suspended services for a mailbox.
NOTE We recommend that you use the newer command GET_MAILBOX_SERVICES instead.
Prerequisites None.
Required • MAILBOX
• DOMAIN
Optional None.
Returns When the command is issued correctly, APP returns the following message:In version 3.4
OK 0SMTPRELAY="T" WEBMAIL="F" SMTPIN="T" IMAP="T" POP="T"
In version 3.5
OK 0SMTPIN="T" SMTPRELAY="T" IMAP="T" WEBMAIL="F" POP="T" SMTPRELAY_WEBMAIL="T"
Errors • 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is forward-only or alias)
SET_MAILBOX_STATUS
Syntax SET_MAILBOX_STATUS MAILBOX="<mailbox>" DOMAIN="<domain>" AUP_VIOLATION="T|F"
IMPORTANT: SET_MAILBOX_STATUS has been deprecated. Instead, use SET_MAILBOX_SERVICES.
Chapter 3 APP Commands Mailbox commands 80
Account Provisioning ProtocolDeveloper’s Guide
Description Sets the status flag for a mailbox. The status flag indicates if one or some of a customer’s mailboxes are delinquent in payment, over disk quota, have violated OpenSRS’ Acceptable Usage Policy (AUP), and so on. For example:
SET_MAILBOX_STATUS MAILBOX="roadrunner" DOMAIN="example.com" AUP_VIOLATION="T"
“T” means the option is on, “F” means the option is off.
Prerequisites Company-level permissions.
Required • MAILBOXMailbox name.
• DOMAINDomain name.
Optional Set as T or F for the following:
• AUP_VIOLATIONAUP violation status code.
Errors • 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is forward-only or alias)
GET_MAILBOX_STATUS
Syntax GET_MAILBOX_STATUS MAILBOX="<mailbox>" DOMAIN="<domain>"
IMPORTANT: GET_MAILBOX_STATUS has been deprecated. Instead, use GET_MAILBOX_SUSPENSION
Description Returns the status flags for a mailbox. For example:
GET_MAILBOX_STATUS MAILBOX="leslie" DOMAIN="example.com"
Prerequisites Mailbox-level permissions.
Required • MAILBOXMailbox name.
• DOMAINDomain name.
Optional None.
SET_MAILBOX_STATUS
Chapter 3 APP Commands Mailbox commands 81
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:OK 0QUOTA="F" PAYMENT="F" AUP_INVESTIGATION="F" AUP_VIOLATION="F" OTHER="F" OTHER_SUSPEND="F" OTHER_BOUNCE="F"
Errors • 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is forward_only or alias)
GET_MAILBOX_STATUS
Chapter 3 APP Commands Mailbox commands 82
Account Provisioning ProtocolDeveloper’s Guide
Mailing lists
CREATE_GROUP_ALIAS_MAILBOX
IMPORTANT: Group aliases no longer exist, and all existing group aliases have been converted to forward_only accounts. As a result, the CREATE_GROUP_ALIAS_MAILBOX command is equivalent to the CREATE_MAILBOX_FORWARD_ONLY command. For more information, see “CREATE_MAILBOX_FORWARD_ONLY” on page 88.
Syntax CREATE_GROUP_ALIAS_MAILBOX GROUP_ALIAS_MAILBOX="<mailbox>" WORKGROUP="<group>" DOMAIN="<domain>" ALIAS_TO_EMAIL_CDL="<email1,email2,...,emailN>"[SPAM_LEVEL="<level>"]
Description Creates a group alias—a mailbox that redirects email to a list of specified addresses. For example:
CREATE_GROUP_ALIAS_MAILBOX GROUP_ALIAS_MAILBOX="devteam" WORKGROUP="db-techies" DOMAIN="example.com" ALIAS_TO_EMAIL_CDL="[email protected],[email protected],mary@acm
e.com"
Prerequisites Workgroup level permissions
Required • GROUP_ALIAS_MAILBOXAlias name.
• WORKGROUPWorkgroup name.
• DOMAINDomain name.
• ALIAS_TO_EMAIL_CDLA comma-delimited list of fully-qualified email addresses.
Optional • SPAM_LEVELThe agressiveness level of spam filtering. Valid values are NORMAL, HIGH, VERY HIGH, and "" (none). When set to NORMAL, most spam is caught. When set to HIGH or VERY HIGH, more spam is caught, but the likelihood that non-spam messages (false positives) will be labelled as spam increases accordingly. If this value is not set, the mailbox uses the SPAM_LEVEL setting for the next highest level (for example, domain or company).
Chapter 3 APP Commands Mailbox commands 83
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:OK 0 Group Alias Mailbox created.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 13 Nonexistent workgroup
• 14 Invalid mailbox name syntax
• 16 Mailbox already exists
• 111 Invalid SPAM_LEVEL
• 112 Maximum number jof mailboxes of this type for this domain reached
• 174 Email address in mailing list is not valid
NOTE This command doesn't return errors on non-existing or invalid mailboxes listed in ALIAS_TO_EMAIL_CDL.
GET_GROUP_ALIAS_MAILBOX
IMPORTANT: Group aliases no longer exist, and all existing group aliases have been converted to forward_only accounts. As a result, the GET_GROUP_ALIAS_MAILBOX command is equivalent to the GET_MAILBOX_FORWARD_ONLY command. For more information, see “GET_MAILBOX_FORWARD_ONLY” on page 89.
Syntax GET_GROUP_ALIAS_MAILBOX DOMAIN="<domain>" GROUP_ALIAS_MAILBOX="<mailbox>"
Description Returns a list of email addresses that make up the specified group alias. For example:
GET_GROUP_ALIAS_MAILBOX DOMAIN="example.com" GROUP_ALIAS_MAILBOX="some_people"
Prerequisites Workgroup-level permissions.
Required • DOMAIN – A domain that already exists on the system
• GROUP_ALIAS_MAILBOX – A group-alias mailbox that exists within the specified domain
Optional None
CREATE_GROUP_ALIAS_MAILBOX
Chapter 3 APP Commands Mailbox commands 84
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:OK 0ALIAS_TO_EMAIL_CDL=""SPAM_LEVEL="NORMAL"
• SPAM_LEVELThe agressiveness level of spam filtering. Valid values are NORMAL, HIGH, VERY HIGH, and "" (none).
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is normal, alias, or forward-only)
CHANGE_GROUP_ALIAS_MAILBOX
IMPORTANT: Group aliases no longer exist, and all existing group aliases have been converted to forward_only accounts. As a result, the CHANGE_GROUP_ALIAS_MAILBOX command is equivalent to the CHANGE_MAILBOX_FORWARD_ONLY command. For more information, see “CHANGE_MAILBOX_FORWARD_ONLY” on page 90.
Syntax CHANGE_GROUP_ALIAS_MAILBOX DOMAIN="<domain>" GROUP_ALIAS_MAILBOX="<mailbox>" ALIAS_TO_EMAIL_CDL="<email1,email2,...emailN>"[SPAM_LEVEL="<level>"]
Description Replaces the list of email addresses that belong to a group alias mailbox. For example:
CHANGE_GROUP_ALIAS_MAILBOX DOMAIN="example.com" GROUP_ALIAS_MAILBOX="tigroup" ALIAS_TO_EMAIL_CDL="[email protected],[email protected]"
Prerequisites Workgroup-level permissions.
Required • DOMAINMust be an existing domain.
• GROUP_ALIAS_MAILBOXMust be an existing group-alias mailbox.
GET_GROUP_ALIAS_MAILBOX
Chapter 3 APP Commands Mailbox commands 85
Account Provisioning ProtocolDeveloper’s Guide
Optional • ALIAS_TO_EMAIL_CDLA comma-delimited list of fully-qualified email addresses.
NOTE The command does not check that the email addresses are valid.
• SPAM_LEVELThe agressiveness level of spam filtering. Valid values are NORMAL, HIGH, VERY HIGH, and "" (none). When set to NORMAL, most spam is caught. When set to HIGH or VERY HIGH, more spam is caught, but the likelihood that non-spam messages (false positives) will be labelled as spam increases accordingly. If this value is not set, the mailbox uses the SPAM_LEVEL setting for the next highest level (for example, domain or company).
Returns When the command is issued correctly, APP returns the following message:OK 0 Group Alias Mailbox changed.
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if normal, alias, or forward-only)
• 111 Invalid SPAM_LEVEL
DELETE_GROUP_ALIAS_MAILBOX
IMPORTANT: Group aliases no longer exist, and all existing group aliases have been converted to forward_only accounts. As a result, the DELETE_GROUP_ALIAS_MAILBOX command is equivalent to the DELETE_MAILBOX_FORWARD_ONLY command. For more information, see “DELETE_MAILBOX_FORWARD_ONLY” on page 91.
Syntax DELETE_GROUP_ALIAS_MAILBOX GROUP_ALIAS_MAILBOX="<mailbox>" DOMAIN="<domain>"
Description Removes a group alias. For example:
DELETE_GROUP_ALIAS_MAILBOX GROUP_ALIAS_MAILBOX="devteam" DOMAIN="example.com"
Prerequisites Workgroup-level permissions.
CHANGE_GROUP_ALIAS_MAILBOX
Chapter 3 APP Commands Mailbox commands 86
Account Provisioning ProtocolDeveloper’s Guide
Required • GROUP_ALIAS_MAILBOX Alias name.
• DOMAINDomain name.
Optional None.
Returns When the command is issued correctly, APP returns the following message:OK 0 Group Alias Mailbox deleted.
Errors • 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is normal, forward_only, or alias)
DELETE_GROUP_ALIAS_MAILBOX
Chapter 3 APP Commands Mailbox commands 87
Account Provisioning ProtocolDeveloper’s Guide
Forward only mailboxes
CREATE_MAILBOX_FORWARD_ONLY
Syntax CREATE_MAILBOX_FORWARD_ONLY MAILBOX="<mailbox>" WORKGROUP="<group>" DOMAIN="<domain>" FORWARD_EMAIL="<email]>"[SPAM_LEVEL="<level>"]
Description Creates a forward-only mailbox. Forward-only mailboxes cost less than regular mailboxes because they don’t accrue charges for data storage. For example:
CREATE_MAILBOX_FORWARD_ONLY MAILBOX="roger" WORKGROUP="dev" DOMAIN="example.com" FORWARD_EMAIL"[email protected]"
Prerequisites Workgroup level permissions
Required • MAILBOXMailbox name.
• WORKGROUPWorkgroup name.
• DOMAINDomain name.
• FORWARD_EMAILThe address, or comma seperated addresses, to forward to. See “Forward address constraints” on page 104.
Optional • SPAM_LEVELThe agressiveness level of spam filtering. Valid values are NORMAL, HIGH, VERY HIGH, and "" (none). When set to NORMAL, most spam is caught. When set to HIGH or VERY HIGH, more spam is caught, but the likelihood that non-spam messages (false positives) will be labelled as spam increases accordingly. If this value is not set, the mailbox uses the SPAM_LEVEL setting for the next highest level (for example, domain or company).
Chapter 3 APP Commands Mailbox commands 88
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox Created
Errors • 14 Invalid mailbox name syntax
• 13 Nonexistent workgroup
• 16 Mailbox already exists
• 111 Invalid SPAM_LEVEL
• 112 Maximum number jof mailboxes of this type for this domain reached
• 171 Forwarding e-mail address is too short.
• 172 Forwarding e-mail address is missing an '@'
• 173 Forwarding e-mail address is missing a '.'
NOTE This command doesn't return errors on non-existing or invalid mailboxes specified in FORWARD_EMAIL.
GET_MAILBOX_FORWARD_ONLY
Syntax GET_MAILBOX_FORWARD_ONLY DOMAIN="<domain>" MAILBOX="<mailbox>"
Description Retrieves the FORWARD_EMAIL contents of an existing forward-only mailbox. For example:
GET_MAILBOX_FORWARD_ONLY DOMAIN="example.com" MAILBOX="kenny"
FORWARD_EMAIL can be up to 4000 printable ASCII characters (Double-quotes are doubled in return value, which may make the returned string longer than the 4000 character limit—but the string will be under limit when the parser strips the extra quotes. Also see “Parsing rules” on page 105.)
Prerequisites Workgroup level permissions
Required • DOMAINMust be a existing domain.
• MAILBOXMust be a forward-only mailbox in that domain.
Optional None.
CREATE_MAILBOX_FORWARD_ONLY
Chapter 3 APP Commands Mailbox commands 89
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:OK 0 [email protected]_LEVEL=<level>
• SPAM_LEVELThe agressiveness level of spam filtering. Value may be NORMAL, HIGH, VERY HIGH, or ""(not set).
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if normal or alias)
CHANGE_MAILBOX_FORWARD_ONLY
Syntax CHANGE_MAILBOX_FORWARD_ONLY DOMAIN="<domain>" MAILBOX="<mailbox>" FORWARD_EMAIL="<email>”[NEW_MAILBOX_NAME="<name>"][SPAM_LEVEL="<level>”]
Description Modifies an existing forward-only mailbox. For example:
CHANGE_MAILBOX_FORWARD_ONLY DOMAIN="example.com" MAILBOX="kenny" FORWARD_EMAIL="[email protected]" NEW_MAILBOX_NAME="newkenny"
Prerequisites Workgroup level permissions
Required • DOMAINMust be a existing domain.
• MAILBOXMust be a forward-only mailbox in that domain.
NOTE You must specify at least one of the optional attributes.
GET_MAILBOX_FORWARD_ONLY
Chapter 3 APP Commands Mailbox commands 90
Account Provisioning ProtocolDeveloper’s Guide
Optional • FORWARD_EMAILNot checked for validity (same as CREATE_MAILBOX_FORWARD_ONLY).
• NEW_MAILBOX_NAMENew name to which this mailbox will be changed.
• SPAM_LEVELThe agressiveness level of spam filtering. Valid values are NORMAL, HIGH, VERY HIGH, and "" (none). When set to NORMAL, most spam is caught. When set to HIGH or VERY HIGH, more spam is caught, but the likelihood that non-spam messages (false positives) will be labelled as spam increases accordingly. If this value is not set, the mailbox uses the SPAM_LEVEL setting for the next highest level (for example, domain or company).
Returns When the command is issued correctly, APP returns the following message:OK 0 Success
Errors • 10 Nonexistent domain (only in version 3.5 and earlier)
• 14 Invalid mailbox name syntax
• 17 Nonexistent mailbox
• 17 Invalid mailbox type (if normal or alias)
• 111 Invalid SPAM_LEVEL
DELETE_MAILBOX_FORWARD_ONLY
Syntax DELETE_MAILBOX_FORWARD_ONLY MAILBOX="<mailbox>" DOMAIN="<domain>"
Description Deletes a forward-only mailbox. For example:
DELETE_MAILBOX_FORWARD_ONLY MAILBOX="inbox-forward" DOMAIN="example.com"
Prerequisites Workgroup-level permissions.
Required • MAILBOXMailbox name.
• DOMAINDomain name.
Optional None.
CHANGE_MAILBOX_FORWARD_ONLY
Chapter 3 APP Commands Mailbox commands 91
Account Provisioning ProtocolDeveloper’s Guide
Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox deleted
Errors • 17 Nonexistent mailbox
• 17 Invalid mailbox type (if mailbox is normal or alias)
DELETE_MAILBOX_FORWARD_ONLY
Chapter 3 APP Commands Mailbox commands 92
Chapter 4
Timezone values
Below are the valid values for the TIMEZONE attribute used in certain commands:
Timezone value Timezone Includes
Pacific/Wake GMT -12:00 Wake Island
Pacific/Niue GMT -11:00 Midway Island, Apia
Pacific/Honolulu GMT -10:00 Hawaii, Cook Islands, Papeete
America/Anchorage GMT -09:00 Anchorage (Alaska Time)
America/Vancouver GMT -08:00 Pacific Time (USA & Canada)
America/Edmonton GMT -07:00 Mountain Time (USA & Canada)
America/Phoenix GMT -07:00 Phoenix, Hermosillo
America/Chicago GMT -06:00 Central Time (USA & Canada)
America/Mexico City GMT -06:00 Guadalajara, Mexico City, Monterrey
America/Guatemala GMT -06:00 Belize, Guatemala, Managua, San Salvador, Tegucigalpa
America/Montreal GMT -05:00 Eastern Time (USA & Canada)
America/Havana GMT -05:00 Havana
America/Lima GMT -05:00 Bogota, Kingston, Lima, Port-au-Prince, Quito
America/Caracas GMT -04:30 Caracas
America/Halifax GMT -04:00 Atlantic Time (USA & Canada)
America/Asuncion GMT -04:00 Asuncion
93
Account Provisioning ProtocolDeveloper’s Guide
America/Santiago GMT -04:00 San Juan, Santiago, Rio Branco
America/Puerto_Rico GMT -04:00 Puerto Rico
America/La_Paz GMT -04:00 La Paz
America/St_Johns GMT -03:30 Newfoundland Time
America/Sao_Paulo GMT -03:00 Rio de Janeiro, Sao Paulo
America/Montevideo GMT -03:00 Montevideo
America/Buenos_Aires GMT -03:00 Buenos Aires, Cayenne
Atlantic/South_Georgia GMT -02:00 South Georgia and the South Sandwich Islands
America/Noronha GMT -02:00 Mid-Atlantic (Fernando de Noronha Time)
Atlantic/Azores GMT -01:00 Ponta Delgada (Azores Time)
Atlantic/Cape_Verde GMT -01:00 Praia (Cape Verde Time)
Europe/London GMT 00:00 Dublin, Lisbon, London
Africa/Casablanca GMT 00:00 Casablanca
Atlantic/Reykjavik GMT 00:00 Abidjan, Accra, Reykjavik
Europe/Amsterdam GMT +01:00 Amsterdam, Berlin, Madrid, Paris, Rome, Stockholm
Africa/Algiers GMT +01:00 Algier, Kinshasa, Lagos, Tunis
Asia/Beirut GMT +02:00 Beirut
Europe/Helsinki GMT +02:00 Athens, Bucharest, Helsinki, Riga, Sofia, Vilnius
Europe/Minxk GMT +02:00 Minsk
Europe/Instabul GMT +02:00 Istanbul
Asia/Amman GMT +02:00 Amman
Asia/Damascus GMT +02:00 Damascus
Timezone value Timezone Includes
Chapter 4 Timezone values 94
Account Provisioning ProtocolDeveloper’s Guide
Asia/Jerusalem GMT +02:00 Jerusalem
Africa/Cairo GMT +02:00 Cairo
Africa/Johannesburg GMT +02:00 Johannesburg
Europe/Moscow GMT +03:00 Moscow
Asia/Baghdad GMT +03:00 Baghdad, Khartoum, Mogadishu, Nairobi
Asia/Tehran GMT +03:30 Tehran
Asia/Baku GMT +04:00 Baku (Azerbaijan Time), Yerevan (Armenia Time)
Asia/Dubai GMT +04:00 Abu Dhabi, Dubai, Muscat (Gulf Standard Time)
Indian/Mauritius GMT +04:00 Tblisi (Seychelles), Port Louis (Mauritius), Victoria (Georgia)
Asia/Kabul GMT +04:30 Kabul
Asia/Karachi GMT +05:00 Karachi, Lahore, Faisalabad, Rawalpindi
Asia/Colombo GMT +05:30 Colombo
Asia/Calcutta GMT +05:30 Ahmedabad, Bengaluru, Chennai, Delhi, Hyderabad, Kolkata, Mumbai
Asia/Katmandu GMT +05:45 Biratnagar, Kathmandu, Patan, Pokhara
Asia/Dhaka GMT +06:00 Astana, Almaty, Bishkek, Dhaka, Chittagong, Khulna, Sylhet, Thimphu
Asia/Rangoon GMT +06:30 Cocos Islands, Yangon (Rangoon)
Asia/Bangkok GMT +07:00 Bangkok
Asia/Phnom_Penh GMT +07:00 Hanoi, Jakarta, Phnom Penh
Asia/Hong_Kong GMT +08:00 Kuala Lumpur, Manila, Beijing, Hong Kong, Singapore, Taipei
Australia/Perth GMT +08:00 Perth (Western Australia)
Timezone value Timezone Includes
Chapter 4 Timezone values 95
Account Provisioning ProtocolDeveloper’s Guide
Asia/Tokyo GMT +09:00 Tokyo, Seoul
Australia/Adelaide GMT +09:30 Adelaide (Southern Australia)
Australia/Darwin GMT +09:30 Darwin (Northern Australia)
Australia/Melbourne GMT +10:00 Melbourne
Australia/Brisbane GMT +10:00 Brisbane (Queensland)
Australia/Lord_Howe GMT +10:30 Lord Howe Island
Pacific/Guadalcanal GMT +11:00 Honiara, Guadalcanal (Solomon Islands)
Pacific/Norfolk GMT +11:30 Burnt Pine, Norfolk Island
Pacific/Fiji GMT +12:00 Suva
Pacific/Auckland GMT +12:00 Auckland, Wellington
Asia/Anadyr GMT +12:00 Anadyr
Pacific/Chatham GMT +12:45 Waitangi, Chatham Islands
Pacific/Tongatapu GMT +13:00 Nukualofa, Tonga, Kiribati (Phoenix Islands)
Pacific/Kiritimati GMT +14:00 Kiritimati, Kiribati (Christmas Island)
Timezone value Timezone Includes
Chapter 4 Timezone values 96
Chapter 5
Reference
This chapter includes the following topics:
• “APP data types” on page 97
• “Parsing rules” on page 105
• “Protocol syntax” on page 110
• “Example of APP usage” on page 113
APP data typesThis topic describes the format restrictions of each APP data type and the mapping of types to attribute names. Every input attribute to an APP command is restricted for content to some degree. Entering an invalid value for a particular attribute will result in a syntax error (or a more specific error in some cases: for example, 'nonexistent mailbox').
The name of an attribute implies a certain data type. For example, a MAILBOX attribute has the same format restrictions whether it is used in the command CREATE_MAILBOX or CREATE_MAILBOX_FORWARD_ONLY.
Definitions All attributes are restricted to ASCII text. The following terms for specific subsets of ASCII are used in the type descriptions below:
• digit: 0-9 (ASCII 48-57)
• alphanumeric: 0-9, A-Z, a-z (ASCII 48-57, 65-90, 97-122)
• printable: alphanumeric plus punctuation (ASCII 32-126)
• non-space printable: above, less space (ASCII 33-126)
• period: '.' (ASCII 46)
• dash: '-' (ASCII 45)
• comma: ',' (ASCII 44)
• double-quote: '"' (ASCII 34)
• slash: '/' (ASCII 47)
• backslash: '\' (ASCII 92)
97
Account Provisioning ProtocolDeveloper’s Guide
Data types The following table describes the data types used in the APP:
Keep in mind that the APP syntax requires that double-quotes be doubled in input, to distinguish them from the beginning and end of the value. Since the parser strips out these doubles, they are not counted toward the maximum length of the field. Output returned by the APP also doubles double-quotes, so it can be parsed correctly.
Also see “Parsing rules” on page 105.
Data type Description
Integer One or more digits. Variable length.
String Any printable characters. Variable length.
Boolean One character only, uppercase T or F.
Mailbox Lowercase alpha, no special characters. (If user enters uppercase, APP will change to lowercase.) Max length 64.
Workgroup Alphanumeric, period and dash. The first and last characters must be alphanumeric. Case-insensitive. Max length 30.
Domain Alphanumeric, period and dash. The first and last characters must be alphanumeric. Must contain at least one period. Periods cannot touch other periods or dashes (that is, sequences “..” “.-” and “-.” are not allowed). Case-insensitive. Max length 64.
Password Must contain combination of numbers and letters, and must contain at least 6 characters. Case-sensitive. Max length 54. For more information on creating passwords, see “User name and password rules” on page 103.
IP Address Four 'octets' separated by periods. Each octet is an integer from 0 to 255 (inclusive).
Filename Any printable character other than slash and backslash. Max length 255.
Chapter 5 Reference APP data types 98
Account Provisioning ProtocolDeveloper’s Guide
Input attributes
Attribute Data type
ALIAS_MAILBOX Mailbox
ALIAS_TO_EMAIL_CDL String(4000)
ATTR_NAME String(64)
ATTR_VALUE String(4000)
AUP_INVESTIGATION Boolean
AUP_VIOLATION Boolean
AUTO_RENEW Boolean
CASCADE Boolean
DOMAIN Domain
DURATION Integer (from 1 to 30 inclusive)
EMAIL String(129)
FETCH Boolean
FILENAME Filename
FILTER String(32000)
FIRST_NAME String(30)
FOLDER String(4000)
FORWARD String(2000)
FORWARD_EMAIL String(4000)
GROUP_ALIAS_MAILBOX Mailbox
HANDLE String(65) – alphanumeric only
ICQ_UIN Integer
ID Integer
KEEP_COPY Boolean
Chapter 5 Reference APP data types 99
Account Provisioning ProtocolDeveloper’s Guide
LAST_NAME String(30)
LIBRARY_NAME String (no limit) must be unix path to a linkable library
LIMIT Integer
MAILBOX Mailbox
MAILBOX_LIST String(2000)
MAILBOX_OFFERING_ID Integer
MAIL_CENTER String(90)
NEW_MAILBOX Mailbox
NFY_ADDR String(129)
NFY_NAME String(64)
OFFERING_ID Integer
OLD_MAILBOX Mailbox
OTHER Boolean
OTHER_BOUNCE Boolean
OTHER_SUSPEND Boolean
PASSWORD Password
PAYMENT Boolean
PHONE String(30)
POP_MAILBOX String(4000)
POP_PASSWORD String(4000)
POP_PORT Integer
POP_TEXT String(32000)
SIGNATURE String(4000)
STATE Boolean
SYNC String (unlimited)
Attribute Data type
Chapter 5 Reference APP data types 100
Account Provisioning ProtocolDeveloper’s Guide
Related information• “Rules for creating and deleting domains, workgroups, and mailboxes” on page 9
• “Legal field values” on page 10
• “Parsing rules” on page 105
• Chapter 3, “APP Commands”
TEXT String(4000)
TITLE String(60)
USER Mailbox
VER String (unlimited); must be one of a constrained set
WORKGROUP Workgroup
Attribute Data type
Chapter 5 Reference APP data types 101
Account Provisioning ProtocolDeveloper’s Guide
Mailbox Folder NamesThe APP expects folder names to be encoded as per section 5.1.3 of this RFC: http://www.faqs.org/rfcs/rfc3501.html.
Folders with special characters need to follow these guidelines in order for the APP to accept them.
Using Webmail to encode folder namesWhen you create a folder in Webmail it will result in proper encoding which can then be copied for use by the APP.
TO RETRIEVE THE PROPERLY ENCODED FOLDER NAME:
1) At a CMD.exe or shell prompt, run the command:telnet mail.<company>.com 143
2) Enter the following IMAP command to log in:A LOGIN <USER>@<DOMAIN>.com <PASSWORD>
3) Enter the following IMAP command to get a list of folders:A LIST "" "*"
4) Enter the following IMAP command to end the session:A LOGOUT
Chapter 5 Reference Mailbox Folder Names 102
Account Provisioning ProtocolDeveloper’s Guide
User name and password rulesThis section details the rules that must be adhered to when assigning user names and passwords.
Mailbox user name User names must follow these guidelines:
• Length must not exceed 64 characters.
• The first character must be alphanumeric.
• The only characters that can be used are the letters a to z, numbers 0 to 9, and the underscore, period, and hyphen symbols.
• Underscores cannot be used as the first character.
• Periods cannot be used as the first or last character.
• Two consecutive periods cannot be used.
• Hyphens cannot be used as the first character.
• Diacritics and special characters are not allowed.
Password Passwords must follow these guidelines:
• Length must not exceed 54 characters.
• The only characters that can be used are ASCII characters with the decimal codes 33 and 35 to 126.
• An empty password is not allowed.
• Space (ASCII character 32) is not allowed.
• A subset of ASCII 7-bit character set is allowed, including a to z, A to Z, 0 to 9, and the following special characters: ~ ! @ $ % ^ & * ( ) - _ = + / \ ] [ { } : ; > < , . ‘ | ?
• The following special characters are not allowed: Ö Ä Ü ö ä ü • Double quotation marks are not allowed (ASCII character 34).
• Delete (ASCII character 127) is not allowed.
• System constrain is at FS level.
• Encrypted passwords employing the {MD5}and {CRYPT} formats are allowed.
E.g., PASSWORD=”{CRYPT}KTR.vioix7b7k”
NOTE {...} does not contribute to the password length.
Chapter 5 Reference User name and password rules 103
Account Provisioning ProtocolDeveloper’s Guide
Mailbox account holder Account holder names must follow these guidelines:
• First and last names must not contain quotes.
For example, first name = ‘Gertrude “Trudy” Miller’ is not allowed; however, first name = ‘Gertrude Trudy Miller’ is allowed.
Forward address constraintsA forwarding address must be:
• > 5 characters
• < than 4000 characters
• in the following format <mailbox> @ <domain> where:
• mailbox must be at least one character
• mailbox must start with an alphanumeric character
• mailbox must contain only alphanumeric characters, dots, hyphens, underscores, and single quotes
• mailbox must NOT have a special character (dot, hyphen, underscore, single quote) followed immediately by another special character
• mailbox must end in an alphanumeric character
• domain must start with an alphanumeric character
• domain must contain at least one dot
• domain must contain only alphanumeric characters, dots and hyphens
• domain must NOT have a special character (dot or hyphen) followed immediately by another special character
• domain must end in an alphanumeric character
Chapter 5 Reference User name and password rules 104
Account Provisioning ProtocolDeveloper’s Guide
Parsing rulesThe APP design parsing is done in layers—the client and server have different parsing layers.
Some definitions
Whitespace
Space, tab or line feed
Label
A string of capital letters, numbers, and “_”
Double-quoted string
A string of arbitrary characters surrounded by double-quotes.
To embed a double-quote within a double-quoted string, use two double-quotes.
To indicate that two double-quoted strings be concatenated, separate them with white space. This is useful to split a long string into two shorter strings to improve its readability.
For example, if your code looks like this:
"This ""is a ""long"" string."
The parser interprets your string like this:
This is a "long" string.
Client syntax parsing
Command
The server grabs lines of data until it finds a line that just has a period.
It discards the line containing the period, and considers the rest a command.
Before CREATE_WORKGROUP WORKGROUP="workgroup" DOMAIN="domain.net".
After CREATE_WORKGROUP WORKGROUP="workgroup" DOMAIN="domain.net"
Chapter 5 Reference Parsing rules 105
Account Provisioning ProtocolDeveloper’s Guide
Command Name
The server throws away any leading whitespace, then grabs everything until the next whitespace, and considers this to be the command name. Note that the command name should be a valid label, and therefore shouldn’t contain any characters that are illegal in a label.
Before CREATE_WORKGROUP WORKGROUP="workgroup" DOMAIN="domain.net"
After
Token:
CREATE_WORKGROUP
Remainder:
WORKGROUP="workgroup" DOMAIN="domain.net"
Attribute-Value Pairs
Each attribute-value pair consists of:
• Label (the attribute name)
• Optional whitespace
• “=”
• Optional whitespace
• Double-quoted-string
Each attribute-value pair is separated from each other by one or more whitespace characters.
Note that a command may have zero or more attribute-value pairs.
Before WORKGROUP=”workgroup” DOMAIN=”DOMAIN.NET”
After
Tokens:
WORKGROUP="workgroup" DOMAIN="domain.net"
Attribute Name & double-quoted value
Each attribute-value pair consists of one attribute name and its associated value. Given an attribute-value pair, the APP parses as follows:
• Discards leading whitespace
• Takes the label (up to a whitespace or “=”) as the attribute name
Chapter 5 Reference Parsing rules 106
Account Provisioning ProtocolDeveloper’s Guide
• Discards the “=”, and the optional whitespace characters that precede, and follow it.
• Takes the double-quoted string as the double-quoted value.
Before WORKGROUP="workgroup"
After
Tokens:
WORKGROUP "workgroup"
Value
To get the value from the double quoted value, the APP discards any leading and trailing whitespace, and also discards the leading and trailing double-quote. Then, it converts any substrings of two double-quotes and replaces them with a single double-quote.
Before "workgroup"
After
Token:
workgroup
Parsing the value further
Depending on the context of a particular command and attribute, a value may have its own internal structure, which may be parsed according to some rules. An example might be a value which contains a comma-delimited list.
Server syntax parsing
Response
The server responds to a command with some data followed by a line containing just a period. The client grabs everything but the line containing just the period, and considers that to be the response.
Before
OK 0 It’s all goodMAILBOX="sifl" WORKGROUP="staff".
After
OK 0 It’s all goodMAILBOX="sifl" WORKGROUP="staff"
Chapter 5 Reference Parsing rules 107
Account Provisioning ProtocolDeveloper’s Guide
Status line
The first line returned by server will always be the error (or success) code. It will start with “OK” or “ER”, followed by an integer (the error code), optionally followed by some whitespace and an ASCII string.
Warning: Your client should never call the optional ASCII string—it is meant as a convenient status comment only and may break your script if the comment changes in future versions of the APP.
Before OK 0 It’s all goodMAILBOX="sifl" WORKGROUP="staff"
After
Tokens:
OK 0
Remainder:
MAILBOX="sifl" WORKGROUP="staff"
Other response data
All commands respond with the above data. Any other data returned by the server depends upon the context of which command was issued. Some commands return no rows, some return one row, and others return multiple rows.
Rows do not necessarily map to lines; as a result, a row may span multiple lines. A command that returns one row is basically a list of attribute-value pairs.
Before
MAILBOX="sifl" WORKGROUP="staff"
After
Tokens:
MAILBOX "sifl" WORKGROUP "staff"
Multiple rows consist of one or more attribute names, each separated by whitespace, followed by a line containing just a comma. After that will be zero or more sets of double-quoted values, each set delimited by a line containing only a comma.
Chapter 5 Reference Parsing rules 108
Account Provisioning ProtocolDeveloper’s Guide
Before
MAILBOX DOMAIN WORKGROUP,"sifl" "domain.net" "staff","ollie" "domain.net" "staff"
After
Tokens:
MAILBOX DOMAIN WORKGROUP "sifl" "domain.net" "staff" "ollie" "domain.net" "staff"
Value
In the case of one row and multiple row responses, the double-quoted values may be parsed to be rid of the quoting. Follow the same double-quoting rules as above.
Before "embedded ""quotes"""
After embedded "quotes"
Parsing the response further
In the case of one row or multiple row responses, some of the values may be able to be parsed further, depending on the context of the command and the attribute.
Chapter 5 Reference Parsing rules 109
Account Provisioning ProtocolDeveloper’s Guide
Protocol syntaxThe protocol syntax is defined in Augmented Backus-Naur Form (ABNF). See Section III, Part A of RFC733 for details on the notational conventions of ABNF.
The protocol syntax is defined in Augmented Backus-Naur Form (ABNF). See Section III, Part A of RFC733 for details on the notational conventions of ABNF.
; ( Decimal.)CHAR = any TELNET ASCII character ; ( 0.-127.)PRINT-CHAR = any TELNET ASCII printable character ; ( 33.-126.)ALPHA = any TELNET ASCII alphabetic character ; ( 65.- 90.) ; ( 97.-122.)CAPITAL = any TELNET ASCII capital alphabetic character> ; ( 65.- 90.)DIGIT = any TELNET ASCII digit ; ( 48.- 57.)NONZERO-DIGIT = any TELNET ASCII digit but zero ; ( 49.- 57.)CR = TELNET ASCII carriage return; ( 13.)LF = TELNET ASCII linefeed ; ( 10.)SPACE = TELNET ASCII space ; ( 32.)HTAB = TELNET ASCII horizontal-tab ; ( 9.)NQCHAR = any TELNET ASCII character excepting double-quote ; ( 0.- 33.) ; ( 35.-127.)DQUOTE = TELNET ASCII double-quote mark ; ( 34.)CRLF = CR LFWHITESPACE = SPACE / HTAB / CRLFq-string = DQUOTE *(qchar) DQUOTE / q-string 1*WHITESPACE DQUOTE *(qchar) DQUOTEqchar = NQCHAR / DQUOTE DQUOTEattribute = labelcommand-name = labellabel = 1*30(CAPITAL / DIGIT / "_")value = q-stringclnt-session = *(command-delim CRLF "." CRLF); See state diagram for ; more detailscommand-delim = command CRLF "."command = *WHITESPACE command-name *(1*WHITESPACE attr-val-pair) *WHITESPACEattr-val-pair = attribute *WHITESPACE "=" *WHITESPACE valuesvr-session = greeting *(response) ; See state diagram for ; more detailsgreeting = "HI APP" SPACE ver CRLF "." CRLFver = NONZERO-DIGIT [DIGIT] "." DIGIT [NONZERO-DIGIT]response = status CRLF [(one-row / multi-row)] CRLF "." CRLFstatus = ("OK" SPACE 0 / "ER" SPACE err-code) [SPACE stat-comment]
Chapter 5 Reference Protocol syntax 110
Account Provisioning ProtocolDeveloper’s Guide
err-code = NONZERO-DIGIT *2DIGITstat-comment = 1*80(PRINT-CHAR / SPACE)one-row = attr-val-pair (SPACE / CRLF) one-row / attr-val-pairmulti-row = attribute-row [CRLF "," CRLF 1*(value-rows)]attribute-row = attribute SPACE attribute-row / attributevalue-rows = value-row CRLF "," CRLF value-rows / value-rowvalue-row = value SPACE value-row / value ; There must be the same ; number of attributes ; in attribute-row as ; there are values in ; value-row
Related information• “Rules for creating and deleting domains, workgroups, and mailboxes” on page 9
• “Legal field values” on page 10
• “APP data types” on page 97
• Chapter 3, “APP Commands”
• Section III, Part A of RFC733 (notational conventions for ABNF)
Chapter 5 Reference Protocol syntax 111
Account Provisioning ProtocolDeveloper’s Guide
Java prerequisiteWhen using the Java APP client to connect to app.hostedemail.com, failures may result unless the proper version of Java is installed on the client. This section describes how to identify a Java version problem and solutions to correct the Java version issue.
The cause of this problem is that the version of Java used on the client side does not acknowledge the server certificate used for app.hostedemail.com. OpenSRS currently uses Equifax for their certificate authority. Versions of Java prior to 1.4.1_12 do not have the necessary Equifax root certificate in their keystore.
Example errorThis issue produces the following error:
javax.net.ssl.SSLHandshakeException:java.security.cert.CertificateException: Could not find trusted certificate
Identifying the problemTo confirm the problem on the client side, run the following command:
keytool -listfor the defaults, orkeytool -list -keystore CACERTS_FILE -storepass PASSWORD
Replacing CACERTS_FILE with the path of the cacerts file within the java directory, and PASSWORD with the password if any.
SolutionTo fix this problem, either install a newer version of Java, at least 1.4.1_12 for the Equifax root certificate, or install the necessary root certificate into the java keystore.
To correct the problem by importing a new certificate, run the following command:
keytool -import -trustcacerts -alias ANYNAME -file FILENAME.cer -keystoreCACERTS_FILE -storepass PASSWORD
Where ANYNAME is a made up name, hopefully mnemonic, FILENAME.cer is the file path of the cer encoded root certificate, CACERTS_FILE is the path of the cacerts file if not the default, and PASSWORD is the password of the cacerts file, if any.
Chapter 5 Reference Java prerequisite 112
Account Provisioning ProtocolDeveloper’s Guide
Example of APP usageThe following example includes server responses in red.
HI APP.VER VER="3.4"..OK 0 Version accepted.LOGIN USER="admin" DOMAIN="companyadmindomain.adm" PASSWORD="abc123"..OK 0 Login accepted.CREATE_DOMAIN DOMAIN="demo_test_domain.com" TIMEZONE="Europe/ Helsinki" LANG="de"..ER 8 Invalid domain name syntax.Domain Name does not comply with RFC conventions.CREATE_DOMAIN DOMAIN="demotestdomain.com" TIMEZONE="Europe/Helsinki" LANG="de"..OK 0 Domain created..CREATE_DOMAIN_ALIAS DOMAIN="demotestdomain.com" ALIAS="aliastodemotestdomain.com"..OK 0 Domain created..CREATE_MAILBOXMAILBOX="support"PASSWORD="sw0rdf1sh"DOMAIN="demotestdomain.com"WORKGROUP="staff"FIRST_NAME="Demo Test Support"..OK 0 Mailbox created..GET_MAILBOX DOMAIN="demotestdomain.com" MAILBOX="support"..OK 0 SuccessFIRST_NAME="Demo Test Support" LAST_NAME="" PHONE="" FAX="" TITLE="" DOMAIN="demotestdomain.com" MAILBOX="support" PASSWORD="{MD5} $1$hbdptrip$fngZ.OlAWdUOZrkWhTR8s1" TIMEZONE="Europe/Helsinki" LANG="de" FILTERONLY="F".CREATE_DOMAIN_WELCOME_EMAIL DOMAIN="demotestdomain.com"WELCOME_SUBJECT="Welcome to Demo Test Domain Dot Com Industries Webmail"WELCOME_TEXT="Hello and welcome to Demo Test Domain Dot Com Industries Webmail
Chapter 5 Reference Example of APP usage 113
Account Provisioning ProtocolDeveloper’s Guide
Everything is awesome here
Have A Nice Day
"FROM_NAME="Demo Test Support"FROM_ADDRESS="[email protected]"CHARSET="utf8"MIME_TYPE="text/plain"..OK 0 Welcome Email attributes created for the domain.CREATE_WORKGROUP WORKGROUP="users" DOMAIN="demotestdomain.com"..OK 0 Workgroup created..CREATE_MAILBOXMAILBOX="jsmith"PASSWORD="{MD5}$1$bananas8$3P6.SlMChP92TYTFm/72j0"DOMAIN="demotestdomain.com"WORKGROUP="users"FIRST_NAME="John"LAST_NAME="Smith"..OK 0 Mailbox created..VERIFY_PASSWORD MAILBOX="jsmith" DOMAIN="demotestdomain.com" PASSWORD="WrongPassword"..OK 0 successVALID="F".VERIFY_PASSWORD MAILBOX="jsmith" DOMAIN="demotestdomain.com" PASSWORD="YourBirthday"..OK 0 successVALID="T".GET_MAILBOX_SUSPENSION MAILBOX="jsmith" DOMAIN="demotestdomain.com"..OK 0SMTPIN="F" SMTPRELAY="F" IMAP="F" WEBMAIL="F" POP="F".SET_MAILBOX_SUSPENSION MAILBOX="jsmith" DOMAIN="demotestdomain.com" WEBMAIL="T"..OK 0.GET_MAILBOX_SUSPENSION MAILBOX="jsmith" DOMAIN="demotestdomain.com"..OK 0
Chapter 5 Reference Example of APP usage 114
Account Provisioning ProtocolDeveloper’s Guide
SMTPIN="F" SMTPRELAY="F" IMAP="F" WEBMAIL="T" POP="F".DELETE_DOMAIN_ALIAS ALIAS="aliastodemotestdomain.com"..OK 0 Alias Deleted..QUIT..OK 0 Bye.
Chapter 5 Reference Example of APP usage 115
Chapter 6
Glossary
A
administration privileges
Administration privileges are meant to limit the actions administrators can perform on mailboxes within a company or domain. There are four levels of administration privilege for logins: company, domain, workgroup, and user.
Company administrators are the highest level of administrator; they can add domain administrators and add or delete domains.
Domain administrators can add and remove workgroups and workgroup administrators, as well as access all mailboxes and workgroups at the domain level.
Workgroup administrators have privilege over one or more workgroups, which are container units for mailboxes that sit inside domains. A typical workgroup might be “sales.” A sales administrator, then, would be responsible for administering just those mailboxes in the sales workgroup, within a particular domain. Workgroups make it possible to break up the administration job into more than one unit and hand this work off to separate people.
Users have the least level of administration privilege; they have access to and can change preferences on their own mailboxes.
alias
A mailbox name that points to an existing mailbox, created using CREATE_ALIAS_MAILBOX.
auto responder
A mailbox property that enables automated responses to incoming mail. If the auto respond feature is active, the mailbox will automatically respond to any incoming mail with a preset message, set in the “text” variable. To reduce duplicate messages, the auto responder mails each address only once per day.
116
Account Provisioning ProtocolDeveloper’s Guide
AUP-Acceptable Use Policy
OpenSRS’ AUP provides guidelines for the sending and receiving of email. For example, the AUP includes information on unsolicited bulk email and lists customers’ rights regarding email service.
B
boolean
Used as an APP data type, BOOLEAN is defined as one character only, uppercase T or F.
C
catch-all
Any mail sent to a nonexistent mailbox in the domain will go to a catch-all mailbox instead of bouncing.
company administrator
See “administration privileges” on page 116.
D
domain
Used as an APP data type, DOMAIN is defined as alphanumeric, period and dash. The first and last characters must be alphanumeric. Must contain at least one period. Periods and dashes cannot touch (for example, the following sequences are not allowed: “..” “--” “.-” and “-.”). Case-insensitive. Max length 64.
domain administrator
See “administration privileges” on page 116.
F
fully-qualified
An email address that is functional—messages sent to it don’t bounce.
Chapter 6 Glossary 117
Account Provisioning ProtocolDeveloper’s Guide
forward-only
A forward-only mailbox is just that—its purpose is to forward mail. Forward-only mailboxes cost less than regular mailboxes because they don’t accrue fees for storing data.
G
group alias
A group alias is a mailbox that redirects email to a list of specified addresses.
I
Integer
Used as an APP data type, INTEGER is defined as one or more digits of variable length.
IP_address
When used as an APP data type, IP_ADDRESS is defined as four octets separated by periods. Each octet is an integer from 0 to 255 (inclusive).
L
Live
Live is a term synonymous with “production”. Any changes you make to this area become available to your customers or users. Login to admin.<cluster>.hostedemail.com, port 4449.
M
mailbox
Used as an APP data type, MAILBOX is defined as alphanumeric, period and dash. The first and last characters must be alphanumeric. Case-insensitive. Max length 64.
mailbox type
A mailbox can be one of the following types: normal (regular user account), forward-only, alias, or group alias. Alt-pop and catch-all are attributes of a normal mailbox.
Chapter 6 Glossary 118
Account Provisioning ProtocolDeveloper’s Guide
N
nickname
A mailbox name which points to an existing mailbox.
notification address
An email address associated with an existing mailbox. This information can be used to automatically forward messages to one or more addresses through the use of server-side mail filters.
P
password
Used as an APP data type, PASSWORD is defined as any non-space printable characters. Case-sensitive. Max length 54. For guidelines on creating user names and passwords, see “User name and password rules” on page 103.
production server
The APP production server is “live.” Any changes you make to this area become available to your customers or users. Login to admin.<cluster>.hostedemail.com, port 4449.
provisioning
Provisioning refers to the events involved in managing OpenSRS services (creating new mailboxes, deleting mailboxes, adding or removing administration privileges, and so on).
S
string
Used as an APP data type, STRING is defined as any printable characters, variable length.
T
test
Staging area for testing and development. Login to admin.test.hostedemail.com, port 4449.
Chapter 6 Glossary 119
Account Provisioning ProtocolDeveloper’s Guide
W
Web Mail
OpenSRS Email Service’s Web-based email.
workgroup
Workgroups are container units for mailboxes and sit inside domains. A typical workgroup might be “sales.” A sales administrator, then, would be responsible for administering just those mailboxes in the sales workgroup, within a particular domain. Workgroups make it possible to break up the administration job into more than one unit and hand this work off to separate people.
Used as an APP data type, WORKGROUP is defined as alphanumeric, period and dash. The first and last characters must be alphanumeric. Case-insensitive. Max length 30.
Chapter 6 Glossary 120
Account Provisioning ProtocolDeveloper’s Guide
Revisions
Date Revision Notes
09-20-2012 You can now add up to 1000 entries in the safe and block lists.
01-10-2012 Updated the list of timezone values in the Timezones chapter..
10-21-2011 There are differences in the information that is returned for some commands in version 3.4, 3.5, and 3.6. Noted the differences and added examples to illustrate.
In version 3.4 and later, group aliases no longer exist, and all existing group aliases have been converted to forward_only accounts. As a result, the following commands have been changed:
• CREATE_GROUP_ALIAS_MAILBOX is now equivalent to CREATE_MAILBOX_FORWARD_ONLY .
• GET_GROUP_ALIAS_MAILBOX is now equivalent to GET_MAILBOX_FORWARD_ONLY
• CHANGE_GROUP_ALIAS_MAILBOX is now equivalent to CHANGE_MAILBOX_FORWARD_ONLY
• DELETE_GROUP_ALIAS_MAILBOX is now equivalent to DELETE_MAILBOX_FORWARD_ONLY
12-14-2010 Updated the list of timezone values in the Timezones chapter.
10-28-2010 Added da (Danish), no (Norwegian), and sv (Swedish) as values for the Language argument..
04-20-2010 Removed CREATE_MAILBOX_NFY_ADDR and DELETE_MAILBOX_NFY_ADDR commands, which are no longer valid.
02-22-2010 Removed GET_MAILBOX_FILTER command.
10-22-2009 New Commands
• GET_DOMAIN_BRAND—displays the brand that is associated with the domain
• SET_DOMAIN_BRAND—assigns a brand to the domain
Revisions 121
Account Provisioning ProtocolDeveloper’s Guide
10-01-2009 New Commands
GET_DOMAIN_MAILBOX_LIMITS—returns the limits for each mailbox type
SET_DOMAIN_MAILBOX_LIMITS—set the number of mailboxes of each type that can be created
Modified Commands
• GET_DOMAIN—now returns DISABLED="T|F”
• SET_DOMAIN_DISABLED_STATUS—now takes arguments DOMAIN and DISABLED="T|F"
03-26-2009 Added optional parameter SPAM_LEVEL to the following commands: CREATE_DOMAIN, CHANGE_DOMAIN, GET_DOMAIN, CREATE_MAILBOX, CHANGE_MAILBOX, GET_MAILBOX, GET_MAILBOX_ANY, CREATE_GROUP_ALIAS_MAILBOX, CHANGE_GROUP_ALIAS_MAILBOX, GET_GROUP_ALIAS_MAILBOX, CREATE_MAILBOX_FORWARD_ONLY, GET_MAILBOX_FORWARD_ONLY, and CHANGE_MAILBOX_FORWARD_ONLY
01-06-2009 Removed SET_MAILBOX_FILTER command.
12-11-2008
10-30-2008
Added Dutch (nl) as a value for the Language argument.
Modified Commands
“CREATE_MAILBOX” &” CHANGE_MAILBOX”
Changed description of SPAM_FOLDER to:
Specifies the folder into which spam will be delivered for the mailbox with the following parameters: argument max length is 128 characters and should take the form of a dot separated folder path; individual folders cannot exceed 30 characters.
10-01-2008 Added “Forward address constraints” on page 104.
09-19-2008 Added “Mailbox Folder Names” and “Using Webmail to encode folder names” on page 102.
09-04-2008 “GET_MAILBOX_ANY” now returns ALIAS_TO.
“Mailbox Folder Names” on page 102 added to alert users to requirements around international characters.
Date Revision Notes
Revisions 122
Account Provisioning ProtocolDeveloper’s Guide
07-25-2008 Reissued under OpenSRS without change.
07-23-2008 Correction
“DELETE_DOMAIN_ALIAS” command: removed the optional argument DOMAIN. The command does not expect this argument and will return an error if it is submitted.
Modified Commands
The following commands have been modified to employ the optional arguments SPAM_TAG and SPAM_FOLDER:
• “CREATE_DOMAIN”
• “GET_DOMAIN”
• “CHANGE_DOMAIN”
• “CREATE_MAILBOX”
• “CHANGE_MAILBOX”
• “GET_MAILBOX”
• “GET_MAILBOX_ANY”
05-02-2008 Republished without change.
04-07-2008 General
All URLs updated to reflect addition of server cluster. (For information about clusters and DNS, refer to the DNS Configuration Guide.)
Mailbox and Workgroup names no longer accept the apostrophe, or single-quote, as a valid character.
Modified Commands
LIMIT parameter for GET_COMPANY_DOMAINS increased to 1000000.
LIMIT parameter for GET_DOMAIN_MAILBOXES increased to 2000000.
Date Revision Notes
Revisions 123
Account Provisioning ProtocolDeveloper’s Guide
03-24-2008 The following Timezone values have been added:
• Asia/Tehran
• Asia/Kabul
• Asia/Katmandu
• Asia/Rangoon
• Pacific/Tongatapu
• America/St_Johns
• America/Caracas
03-06-2008 Workgroup Commands
Added Returns to commands.
Mailbox Commands
Mailbox commands have been reordered under the following subheadings:
• General
• Options (Settings)
• Suspension and reinstatement
• Mailing lists
• Forward only mailboxes
03-05-2008 Mailbox Commands
Minor edits and typographic corrections have been made to clarify command syntax and examples.
A Returns section has been added to each command. This information previously appeared in some command descriptions. Any command missing this description in the current document will be updated as soon as possible.
02-29-2008 Domain Commands
Minor edits and typographic corrections have been made to clarify command syntax and examples.
A Returns section has been added to each command. This information previously appeared in some command descriptions. Any command missing this description in the current document will be updated as soon as possible.
Date Revision Notes
Revisions 124
Account Provisioning ProtocolDeveloper’s Guide
02-13-2008 “Example of APP usage” updated.
02-07-2008 General
The argument ENCRYPTED has been removed from all commands in which it occurred. Password encryption can be set in the PASSWORD argument using {MD5} or {CRYPT}, see “Password” on page 103.
The description for “CREATE_DOMAIN” has been modified to reflect the fact that this command no longer creates a postmaster mailbox.
New Commands
• “SET_MAILBOX_SUSPENSION” on page 79
• “GET_MAILBOX_SUSPENSION” on page 80
Deprecated Commands
• SET_MAILBOX_STATUS has been replaced by SET_MAILBOX_SUSPENSION.
• GET_MAILBOX_STATUS has been replaced by GET_MAILBOX_SUSPENSION.
Date Revision Notes
Revisions 125
Account Provisioning ProtocolDeveloper’s Guide
02-01-2008 General
The APP Developer’s Guide is the authoritative documentation of the APP tool and supersedes the APP HELP command.
The HELP command has been removed until such time as it can be brought in line with this guide.
The argument LANGUAGE is preferred to LANG and should always be used. LANG is slated for removal.
New Commands• CREATE_DOMAIN_ALIAS, see page 17
• DELETE_DOMAIN_ALIAS, see page 18
Modified Commands• CREATE_DOMAIN
added the optional arguments FILTERMX
• CHANGE_DOMAINadded three optional arguments: LANGUAGE, TIMEZONE and DATEFORMAT.
• CREATE_MAILBOXadded optional argument: FILTERONLY
• CHANGE_MAILBOXadded optional argument: FILTERONLY
• GET_MAILBOXFILTERONLY now returned in response
Corrections and Updates• Passwords, see“Password” on page 103.
Password length is between 1 and 54 characters, not 64.
Removed the statement “Only the first 8 characters of a non-encrypted password are significant.” This is no longer true.
Passwords can be encrypted using {MD5} or {CRYPT}.
Date Revision Notes
Revisions 126
Account Provisioning ProtocolDeveloper’s Guide
10-25-2007 General
“Data types” on page 98.
• Restriction of “--” character sequence in Domain names removed as per RFCS. “--” is an allowed value.
New Commands• “SET_MAILBOX_ALLOW_LIST” on page 54
• “GET_MAILBOX_ALLOW_LIST” on page 56
• “SET_MAILBOX_BLOCK_LIST” on page 55
• “GET_MAILBOX_BLOCK_LIST” on page 57
• “SET_DOMAIN_ALLOW_LIST” on page 36
• “GET_DOMAIN_ALLOW_LIST” on page 37
• “SET_DOMAIN_BLOCK_LIST” on page 36
• “GET_DOMAIN_BLOCK_LIST” on page 38
Date Revision Notes
Revisions 127
Index
AABNF 110
Acceptable Use Policy 117
Administration privileges 116
Alias 116
ALIAS_MAILBOX attribute 52
ALIAS_TO_EMAIL_CDL attribute 83
Alphanumeric 97
Architecture of APP 7
Attribute Name & double-quoted value 106
Attributesdatatypes 99
Attribute-Value Pairs 106
AUP 117
Autoresponder 116
BBoolean 117
CCase-insensitive 9
Catch-all 117
CHANGE_DOMAIN 26
CHANGE_GROUP_ALIAS_MAILBOX85
CHANGE_MAILBOX 48
CHANGE_MAILBOX_FORWARD_ONLY 90
Client syntax parsing 105
Comma 97
Command 105
Command Name 106
Commands
domain 16list with full descriptions 13mailbox 43submitting 9syntax 9
Company administrator 117
Company administrators 116
Connections, establishing secure to sandbox or production servers 8
CREATE_ALIAS_MAILBOX 52
CREATE_DOMAIN 16
CREATE_DOMAIN_ADMIN 28
CREATE_DOMAIN_INDEX 17
CREATE_DOMAIN_WELCOME_EMAIL 19
CREATE_GROUP_ALIAS_MAILBOX 83
CREATE_MAILBOX 45
CREATE_MAILBOX_FORWARD_ONLY 88
DDash 97
Datatypes 10, 97attributes 99
DELETE_DOMAIN 17
DELETE_DOMAIN_ADMIN 28
DELETE_DOMAIN_WELCOME_EMAIL 22
DELETE_GROUP_ALIAS_MAILBOX 86
DELETE_MAILBOX 69
DELETE_MAILBOX_ANY 69
DELETE_MAILBOX_FORWARD_ONLY 91
128
Account Provisioning ProtocolDeveloper’s Guide
DELETE_WORKGROUP 40
Digit 97
DISABLE_OFFERING 77
Domain 117commands 16
Domain administrators 116
Double-quote 97
Double-quoted string 105
EENABLE_OFFERING 77
Ending the session 12
FField values 10
FORWARD attribute 74
FORWARD_EMAIL attribute 88
Forwardingchanging the address for a forward-only mailbox 90creating a forward-only mailbox 88returning a forward address 75returning forward-only address for a mailbox 89setting for a mailbox 74
Forward-only 118
Fully-qualified 117
GGET_ADMIN 58
GET_ALTERNATE_MAILBOX_NAMES44
GET_COMPANY_DOMAINS 21
GET_DOMAIN 23
GET_DOMAIN_ALLOW_LIST 37
GET_DOMAIN_BLOCK_LIST 38
GET_DOMAIN_BRAND 25
GET_DOMAIN_MAILBOX_LIMITS 33
GET_DOMAIN_MAILBOXES 32
GET_DOMAIN_WORKGROUPS 39
GET_GROUP_ALIAS_MAILBOX 84
GET_MAILBOX 59
GET_MAILBOX_ALLOW_LIST 56
GET_MAILBOX_ANY 63
GET_MAILBOX_AUTORESPOND 72
GET_MAILBOX_AVAILABILITY 43
GET_MAILBOX_BLOCK_LIST 57
GET_MAILBOX_FORWARD 75
GET_MAILBOX_FORWARD_ONLY 89
GET_MAILBOX_QUOTA 68
GET_MAILBOX_SERVICES 66
GET_MAILBOX_STATUS 81
GET_NUM_DOMAIN_MAILBOXES 31
Glossary 116
Group alias 118creating 83
HHierarchy 9
IIdle connections, timeouts 12
Input attributes 99
Integer 118
ip_address 118
JJava 112
KKEEP_COPY attribute 74
LLabel 105
Legal field values 10
Listscreating group alias or mailing list 83
Logging in 9
Index 129
Account Provisioning ProtocolDeveloper’s Guide
MMailbox 118
commands 43
Mailbox attributeschanging 48returning 59
Mailbox type 118
Mailboxesdeleting 69
Mailing Listcreating 83
NName
guidelines 103, 104
Nickname 119
Nonspace printable 97
Notification address 119
OOther response data 108
Overviewof APP architecture 7
PParsing rules 105
Password 119
Password guidelines 103
Period 97
Ports 8
Printable 97
Production server 119
Protocol syntax 110
Provisioning 119
QQuit 12
RReference 97
RENAME_MAILBOX 53
Response 107
Rules for creating and deleting domains, workgroups, and mailboxes 9
SSandbox
connection 8
Serverestablishing a secure connection 8
Server syntax parsing 107
SET_DOMAIN_ADMIN 28
SET_DOMAIN_ALLOW_LIST 36
SET_DOMAIN_BLOCK_LIST 36
SET_DOMAIN_BRAND 29
SET_DOMAIN_CATCH_ALL_MAILBOX 30
SET_DOMAIN_DISABLED_STATUS 31
SET_DOMAIN_MAILBOX_LIMITS 34
SET_MAIL_ADMIN 47
SET_MAILBOX_ALLOW_LIST 54
SET_MAILBOX_AUTORESPOND 71
SET_MAILBOX_BLOCK_LIST 55
SET_MAILBOX_FORWARD 74
SET_MAILBOX_QUOTA 68
SET_MAILBOX_SERVICES 67
SET_MAILBOX_STATUS 80
SET_WORKGROUP_ADMIN 41
SHOW_AVAILABLE_OFFERINGS 76
SHOW_ENABLED_OFFERINGS 76
STATE attribute 74
Status line 108
String 119
Submitting commands 9
Index 130
Account Provisioning ProtocolDeveloper’s Guide
Syntax 110
Syntax for commands 9
TTesting
connecting to the sandbox 8
time zone 16, 27, 46, 50, 61, 64values 93
Timeouts for idle connections 12
UUsing the APP 8
VValue 107, 109
Valueslegal field values 10
VER 8, 14
VERIFY_PASSWORD 57
Version number of client, specifying 14
Versions 8
WWeb Mail 120
Whitespace 105
Workgroup 120
Workgroup administrators 116
Index 131