OpenSRS Email Service Account Provisioning Protocol · OpenSRS Email Service Account Provisioning Protocol ... Mailing lists ... In the OpenSRS provisioning system,

OpenSRS Email Service AccountProvisioning Protocol

Developer’s GuideSeptember 20, 2012

COPYRIGHT

Copyright 2012 Tucows, Inc. All rights reserved.

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


CHAPTER 6 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

5


6

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


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


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


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


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


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


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


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


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.



• 9 Domain name already exists


• 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



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



Returns When the command is issued correctly, APP returns the following message:OK 0 Alias deleted.




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



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.




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.


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.




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"


• 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



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.


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



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



• 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.


GET_DOMAIN



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.



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.




• 37 Invalid domain type


CHANGE_DOMAIN



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


• 17 Nonexistent mailbox

• 17 Invalid mailbox type (if mailbox is one of type: alias, or forward_only



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"


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



• ER 52 Brand Code not found



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



• 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)



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


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"


Required DOMAIN

Optional None




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"


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




OK 0MAILBOX TYPE WORKGROUP"mb1" "NORMAL" "staff","mb2" "OTHER" "staff","mb3" "NORMAL" "staff"


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.


• 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"


Required DOMAIN

Optional None

GET_DOMAIN_MAILBOXES




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.


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



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


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.


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



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


Errors • 2 Required attribute missing


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.




Required • DOMAIN




Optional None




GET_DOMAIN_ALLOW_LIST

Syntax GET_DOMAIN_ALLOW_LIST DOMAIN="<domain>"

Description Returns the Allow Sender List for the domain.


Required • DOMAIN

Optional None

Returns When the command is issued correctly, APP returns the following message:OK 0List="[email protected]“yahoo.com"



SET_DOMAIN_BLOCK_LIST



GET_DOMAIN_BLOCK_LIST

Syntax GET_DOMAIN_BLOCK_LIST DOMAIN="<domain>"

Description Returns the Block Sender List for the domain.


Required • DOMAIN

Optional None





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.


• 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”


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



OK 0WORKGROUP CREATE_DATE

"staff" "01/01/2004","test1" "01/01/2004"

NOTE The CREATE_DATE value is always listed as 01/01/2004.


OK 0 SuccessWORKGROUP,MAILBOX_COUNT,FORWARD_COUNT,ALIAS_COUNT"994","11","3","5","0""blob","0","0","0","0""bubba","0","0","0","0"


• 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"


Required • WORKGROUPWorkgroup name.

• DOMAINDomain name.

GET_DOMAIN_WORKGROUPS



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.


• 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.


Required • DOMAIN

• MAILBOX

Optional • STATEBoolean T or F. T means grant Workgroup administration privileges (default), while F means remove privileges.

DELETE_WORKGROUP





• 17 Nonexistent mailbox or

• 17 Invalid mailbox type (if mailbox is one of type: alias or forward_only)

SET_WORKGROUP_ADMIN



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"


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.


Chapter 3 APP Commands Mailbox commands 43


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*”



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



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



Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox created.



• 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


• 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"


Required • DOMAIN

• MAILBOX

Optional • STATEBoolean T or F. The default is T.

CREATE_MAILBOX







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



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.


NOTE At least one optional attribute must be set.

CHANGE_MAILBOX



Optional • PASSWORDMust consist entirely of printable, non-space characters. For guidelines on creating passwords, see “User name and password rules” on page 103.




• 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.


• 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



• 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.



• 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)


• 200 Problem in moving mailbox to workgroup

• 207 Invalid Timezone value

CHANGE_MAILBOX



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.





• 112 Maximum number of mailboxes of this type for this domain reached



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.



• 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)



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




Optional None.







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.



• DOMAIN




Optional None.







GET_MAILBOX_ALLOW_LIST

Syntax GET_MAILBOX_ALLOW_LIST DOMAIN="<domain>"MAILBOX="<mailbox>"

Description Returns the Allow Sender List for the mailbox.



• DOMAIN

Optional None.

Returns When the command is issued correctly, APP returns the following message:OK 0 SuccessLIST="*@[email protected]*tucows.com"






GET_MAILBOX_BLOCK_LIST

Syntax GET_MAILBOX_BLOCK_LIST DOMAIN="<domain>" MAILBOX="<mailbox>"

Description Returns the Block Sender List for the mailbox.



• DOMAIN

Optional None.

Returns When the command is issued correctly, APP returns the following message:OK 0 SuccessLIST="*@[email protected]*tucows.com"




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




• 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.



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.




VERIFY_PASSWORD



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"


Required • DOMAINA domain that already exists on the system

• MAILBOXA normal user mailbox that exists within the specified domain




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"


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"



GET_MAILBOX



• TITLEMailbox user’s job title.


• FAX

Mailbox user’s fax number.• DOMAIN

The domain to which the mailbox belongs.

• BRANDThe brand associated with this domain.


• 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



• 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



• 17 Invalid mailbox type (if mailbox is of type alias or forward_only)

GET_MAILBOX



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




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"


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"




• 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).


• 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.


• 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



• 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.



GET_MAILBOX_ANY



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.



• 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"

•






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.



• 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






GET_MAILBOX_QUOTA

Syntax GET_MAILBOX_QUOTA DOMAIN="<domain>"MAILBOX="<mailbox>"

Description Returns the quota (in MB) for the specified mailbox.



• DOMAIN

Optional None.

Returns When the command is issued correctly, APP returns the following message:OK 0 SuccessQUOTA="8192"




SET_MAILBOX_QUOTA

Syntax SET_MAILBOX_QUOTA DOMAIN="<domain>"MAILBOX="<mailbox>" QUOTA="8192"

Description Changes the quota (in MB) for the specified mailbox.



• DOMAIN

• QUOTA

Optional None.







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.


Optional None.

Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox Deleted

Errors • 17 Nonexistent mailbox


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"


Required • DOMAIN

• MAILBOX

Optional None.



Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox Deleted



DELETE_MAILBOX_ANY



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.






• 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



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"


• 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.




GET_MAILBOX_AUTORESPOND



\

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.



• 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.







• 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"


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.



• 17 Invalid mailbox type (if mailbox is alias)

SET_MAILBOX_FORWARD



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"


Required • DOMAIN

• MAILBOX

Optional None




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.


Required • DOMAIN

• MAILBOX

Optional None






DISABLE_OFFERING

Syntax DISABLE_OFFERING MAILBOX_OFFERING_ID="<n>"

Description Disables a currently-enabled offering. For example:

DISABLE_OFFERING MAILBOX_OFFERING_ID="102"


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"


Required • DOMAIN

• MAILBOX

• OFFERING_ID Find OFFERING_ID by looking on the list returned by the SHOW_AVAILABLE_OFFERINGS command.



Optional • AUTO_RENEWA boolean which governs whether the offering should be automatically renewed upon expiration (defaults to “F”).


• 17 Nonexistent mailbox (or “invalid mailbox type” if mailbox is of type alias or forward_only)

• 29 Offering not found

ENABLE_OFFERING



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.


• 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.



• 17 Invalid mailbox type (if mailbox is forward-only or alias)



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.


• 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"



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.



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.




Optional Set as T or F for the following:

• AUP_VIOLATIONAUP violation status code.



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"




Optional None.

SET_MAILBOX_STATUS



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"



GET_MAILBOX_STATUS



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"


Required • GROUP_ALIAS_MAILBOXAlias name.

• WORKGROUPWorkgroup 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).



Returns When the command is issued correctly, APP returns the following message:OK 0 Group Alias Mailbox created.







• 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"


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



Returns When the command is issued correctly, APP returns the following message:OK 0ALIAS_TO_EMAIL_CDL=""SPAM_LEVEL="NORMAL"




• 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]"


Required • DOMAINMust be an existing domain.

• GROUP_ALIAS_MAILBOXMust be an existing group-alias mailbox.

GET_GROUP_ALIAS_MAILBOX



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.


Returns When the command is issued correctly, APP returns the following message:OK 0 Group Alias Mailbox changed.



• 17 Invalid mailbox type (if normal, alias, or forward-only)


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"


CHANGE_GROUP_ALIAS_MAILBOX



Required • GROUP_ALIAS_MAILBOX Alias name.


Optional None.

Returns When the command is issued correctly, APP returns the following message:OK 0 Group Alias Mailbox deleted.


• 17 Invalid mailbox type (if mailbox is normal, forward_only, or alias)

DELETE_GROUP_ALIAS_MAILBOX



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]"



• WORKGROUPWorkgroup 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).



Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox Created

Errors • 14 Invalid mailbox name syntax





• 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.)


Required • DOMAINMust be a existing domain.

• MAILBOXMust be a forward-only mailbox in that domain.

Optional None.

CREATE_MAILBOX_FORWARD_ONLY



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).



• 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"


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



Optional • FORWARD_EMAILNot checked for validity (same as CREATE_MAILBOX_FORWARD_ONLY).

• NEW_MAILBOX_NAMENew name to which this mailbox will be changed.






• 17 Invalid mailbox type (if normal or alias)


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"




Optional None.

CHANGE_MAILBOX_FORWARD_ONLY



Returns When the command is issued correctly, APP returns the following message:OK 0 Mailbox deleted


• 17 Invalid mailbox type (if mailbox is normal or alias)

DELETE_MAILBOX_FORWARD_ONLY


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


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


Chapter 4 Timezone values 94


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)




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)



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


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


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



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



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



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

http://www.faqs.org/rfcs/rfc3501.html


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


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


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


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



• 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"



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.



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.



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


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


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


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


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



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 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


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


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.



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.



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.



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


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


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


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


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


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


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


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


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


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

Documents

OpenSRS Email Service Account Provisioning Protocol · OpenSRS Email Service Account Provisioning Protocol ... Mailing lists ... In the OpenSRS provisioning system,