API: OpenSRS Email

The API: OpenSRS Hosted Email Developer Hub

Welcome to the API: OpenSRS Hosted Email developer hub. You'll find comprehensive guides and documentation to help you start working with API: OpenSRS Hosted Email as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

change_user

The change_user method creates a new user or changes the attributes of an existing user.

Syntax

{
    <credentials object> 
    "user": <name of user to create or change> 
    "attributes":
     {
         <key-value pairs> 
     }
     create_only: TRUE | FALSE
}

Request fields for change_user

The following fields can be used in the change_user method:

Field nameObligationDefinition/Value
attributesRequiredThe list of fields that you want to define or modify and their new values.

For more information, see the Attributes table below.
create_onlyOptionalUsed to prevent changes to existing accounts. If set to true and the specified user exists, the account will not be modified and an error will be returned.
userRequiredThe user that you want to create or modify.

Attributes fields

You can specify the following fields within the attributes array.

Field nameObligationDefinition/Value
aliasesOptionalThe list of alternate names for the account, for example, [email protected], [email protected], [email protected] Mail sent to an alias address is delivered to the account. The alias address can be used to log in to the account via IMAP4, POP3, Webmail and SMTP

The maximum number of aliases is 2,000.
allowOptionalA list of email addresses on the user's allow list; may include wildcards. For example [email protected] and *@example.com. Maximum is 1000 addresses.
autoresponderOptionalThe text of the message that is automatically sent back to senders if delivery_autoresponder is set to true. Maximum size is 4,000 characters.
autoresponder_ option_enddateOptionalThe date that the autoresponder expires, expressed in UNIX Epoch time. If not specified, the autoresponder never expires.
autoresponder_option_intervalOptionalThe number of hours that must pass before the autoresponder message is sent again to the same address. Must be less than 1,095 (45 days). If not set, an interval of 24 hours is used.
blockOptionalA list of email addresses on the user's block list; may include wildcards. For example, [email protected] and *@spammers- inc.com. Messages from these addresses will always be considered to be spam. Maximum is 1000 addresses.
brandOptionalThe Webmail brand for this mailbox. If not specified, the account uses the domain setting.
delivery_ autoresponderOptionalIf set to true, the configured auto response message is sent to the sender.
delivery_filterOptionalIf set to true, messages are scanned and then passed to the domain's filtermx host; the messages are not stored locallly.

Note: If delivery_filter = true, all other delivery attributes must be false.
delivery_forwardOptionalIf set to true, the message is forwarded to the mailbox's forward_recipients list.
delivery_localOptionalIf set to true, the message is passed through the mailbox's sieve filters and stored locally.
x
x

Valid combinations of delivery attributes are

  • delivery_local—Mail is stored locally.
  • delivery_local, delivery_forward—Mail is stored locally and forwarded.
  • delivery_forward—Mail is forwarded.
  • delivery_local, delivery_autoresponder—Mail is stored locally, automatic reply sent.
  • delivery_local, delivery_forward, delivery_autoresponder—Mail is stored locally and forwarded, automatic reply sent.
  • delivery_forward, delivery_autoresponder—Mail is forwarded, automatic reply sent.
  • delivery_filter—Mail is forwarded to domain-defined mail host.

📘

Note:

No matter which delivery options are set, all messages are scanned for viruses and malware, and, depending on the mailbox's allow list, all messages are scanned for spam.

Field nameObligationDefinition/Value
faxOptionalThe fax number for the account owner; can be a maximum of 30 characters.
filterdeliveryOptionalDetermines what happens to spam messages:

quarantine — Spam messages are stored locally in the user's spam folder.

passthrough — Spam messages are delivered with the specified spamtag and spamheader.

If not defined, the account uses the domain's filterdelivery setting.
forward_option_restrictedOptionalIf set to true and delivery_forward is also set to true, only messages from addresses on the forward recipients list are forwarded.
forward_option_subject_prefixOptionalIf delivery_forward is set to true, this string is added to the beginning of the Subject line of forwarded messages. String can be up to 128 characters
forward_option_reply_toOptionalIf delivery_forward is set to true, this email address is added to the Reply-To header of forwarded messages.
forward_ recipientsOptionalIf delivery_forward is set to true, incoming messages will be forwarded to this list of addresses. Maximum number of addresses is 1,000.
languageOptionalThe default language in which the mailbox will be displayed. May be overridden by the user.

A list of valid language names is displayed in the metadata ->options field in the get_user response.
macsettingsOptionalA string that contains the user's MAC UI preferences. Only used by the MAC; not recommended for use by other applications. Maximum 2048 characters.
max_pab_entriesOptionalThe maximum number of entries (contacts and groups) that the user can have in their address book.
nameOptionalThe name that is used in the From field of email messages. The format is UTF-8 text and can be up to 512 characters.
notes_externalOptionalAny notes you want to add to the user. Maximum is 4096 characters.
passwordOptionalThe password used to log in to all services.

Here are the constraints are requirements for passwords:

Can be plain text or hashed.
If plain text, the text can be between 1 and 54 characters (Length must not exceed 54 characters).
If hashed, it is a ASCII string consisting of an hash type in curly braces followed by 1 to 150 characters.
Allowed hash types are: MD5 BCRYPT CRYPT DES SHA SHA1 SHA224 SHA256 SHA384 SHA512 SSHA SSHA1 SSHA224 SSHA256 SSHA384 SSHA512 GCRYPT (GCRYPT is for glibc hashed SHA and BCRYPT passwords from a shadow file on modern linux distributions).
Passwords are always stored and retrieved hashed. If a plain text password is assigned, it will be hashed before it is stored.
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.
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: Ö (ASCII character 153) Ä (ASCII character 142) Ü (ASCII character 154) ö (ASCII character 148) ä (ASCII character 132) ü (ASCII character 129)
* Double quotation marks are not allowed (ASCII character 34). Delete (ASCII character 127) is not allowed. Space (ASCII character 32) is not allowed.

See section on Password Validation, below.
phoneOptionalThe user's phone number; maximum 30 characters.
quotaOptionalThe maximum amount of storage (in bytes) that the mailbox may use, including mail and file storage.
reject_spamOptionalDetermines whether spam messages are rejected at the SMTP level. Allowed values are true and false.
service_imap4OptionalThe setting for the IMAP4 service (enabled, disabled, or suspended). If enabled, the user can log in via IMAP4.
service_pop3OptionalThe setting for the POP3 service (enabled, disabled, or suspended). If enabled, the user can log in via POP3.
service_smtpinOptionalThe setting for the SMTPIN service (enabled, disabled, or suspended). If enabled, the user can send email.
service_smtprelayOptionalThe setting for the SMTPRELAY service (enabled, disabled, or suspended).
service_smtprelay_web mailOptionalThe setting for the SMTPRELAY Webmail service (enabled, disabled, or suspended). If enabled, the user can send email via Webmail.
service_webmailOptionalThe setting for the Webmail service (enabled, webmail disabled, or suspended). If enabled, the user
can log in via Webmail.

📘

Password Validation

Password Validation can only occur when a plaintext password is sent as part of the API request.

A user changing their own password is subject to an additional password strength test (when req.user == req.credentials.user). Increasing the length of the password and including a mix of symbols, upper and lower case letters, and numbers will increase the calculated strength of a given password. The required minimum strength level is inherited from the password_strength attribute set at the domain, company, or cluster level.

As of V1.1, all password changes are subject to the following check:

  • Contains check: any password supplied during a password update or account creation will be checked to make sure it does not contain the user's username or domain name, and if it does, the password will be rejected. This test is not case-sensitive.

📘

When creating a new user, if a service is not specified in the request, the value of the service attribute is taken from the domain setting. If the domain does not have a value for that service, it is enabled. If a service is suspended in the domain, it can only be set in the request by an admin of the same or higher level than the admin that set the service to suspended in the domain (for example, a domain admin cannot change a service that was suspended by a company admin).

Field nameObligationDefinition/Value
sieveOptionalThe user's sieve filters.
smtp_sent_limitOptionalThe number of messages that the user is allowed to send in a 24 hour period. Maximum number is 10,000. If not defined, the domain's smtp_sent_limit is used.

Note: If the same message is sent to two recipients, it counts as two messages against this limit.
spamfolderOptionalThe folder into which messages identified as spam will be delivered. Maximum 128 characters. Nested folders are separated by the '/' character, for example, "Archive/Junk/Spam" If not defined, the mailbox uses the domain's spamfolder setting.
spamheaderOptionalThe tag that is added to messages that are identified as spam. Maximum 512 characters.
spamlevelOptionalThe level of aggressiveness set for the spam filter. Valid values are Normal, High, and Very High. If not set, the mailbox uses the domain's spamlevel setting.
spamtagOptionalThe value of this field is prepended to the subject of any message that is identified as spam. Maximum 30 characters. If not defined, the mailbox uses the domain's spamtag setting.

Note: This value is not supported for filteronly accounts.
timezoneOptionalThe timezone that the mailbox will use.

A list of valid timezones is displayed in the metadata ->options field in the get_user response.
titleOptionalThe user's job title;maximum 60 characters.
typeOptionalDetermines the type of account that is associated with this user. Allowed values are mailbox, forward, or filter. The default type when creating a user is mailbox.

The type value in turn restricts the delivery method that can be specified. Mailbox accounts can have local and/or forward delivery, forward accounts can have only forward delivery, and filter accounts can have only filter delivery. Any incompatible delivery attributes that are submitted will be ignored.
workgroupOptionalThe workgroup to which the user belongs.

Response fields for change_user

The following fields may be returned in response to the change_user method:

Field nameObligationDescription/Value
errorReturned if success = falseA text string that explains the error.
error_numberReturned if success = falseA number that represents the error.
hintsMay by returned when success = falseA list of the attributes that had errors and the reason for each error.
successAlways returnedIndicates whether the request was successful or not. Allowed values are true and false.

Examples for change_user

Example 1

Successfully creates a new user.

Request

{
  "credentials": {
        "user": "[email protected]",
    "password": "sw0rdf1sh"
  },
  "user": "[email protected]",
  "attributes": {
    "name": "Bob Hayden",
    "password": "changeit",
    "delivery_forward": true,
    "forward_recipients": [
        "[email protected]
  }
}

Response

{
   "success": true
}

Example 2

Changes the user's spamtag attribute.

Request

{
  "credentials": {
    "user": "[email protected]",
    "password": "sw0rdf1sh"
  },
  "user": "[email protected]",
  "attributes": {
    "spamtag": "[JUNK]"
  }
}

Response

{
   "success": true
}

Example 3

Attempts to modify an existing user, but fails due to badly formatted attributes.

Request

{
  "credentials": {
        "user": "[email protected]",
    "password": "sw0rdf1sh"
  },
   "user": "[email protected]",
   "attributes": {
      "spamtag": "(SPAM)",
      "name": [
                 "Robson",
                 "Wilk" 
      ],
      "allow": "[email protected]",
      "block": [
         "[email protected]",
         "*@naughty.edu"
      ]
     } 
}

Response

{
   "success": false
   "hints": {
      "name": "Not a valid Text[1-512] (not a string)",
      "allow": "Not a list"
   },
   "error_number": 6,
   "error": "One or more attributes badly formatted" 
}

Example 4

Attempts to create a user that already exists (with create_only flag).

Request

{
  "credentials": {
  "user": "[email protected]",
    "password": "sw0rdf1sh"
  },
  "user":"[email protected]",
  "create_only":true,
  "attributes":{
    "type":"mailbox",
    "password":"gob",
    "reject_spam":false,
    "name":"Bob Hayden",
    "workgroup":"staff"
  } 
}

Response

{
  "success":false,
  "error_number":23,
  "error":"Object already exists",
  "audit":"jewel30_50c235f127"
}

Example 5

Changes a user to a filter.

Request

{
  "credentials": {
    "user": "[email protected]", 
    "password": "sw0rdf1sh"
    },
    "user":"[email protected]",
    "attributes":{
      "type":"filter"
    }
}

Response

{
   "success": true
}

Example 6

Changes a user to a forward.

Request

{
  "credentials": {
    "user": "[email protected]",
    "password": "sw0rdf1sh"
  },
  "user":"[email protected]",
  "attributes":{
    "type":"forward"
  }
}

Response

{
   "success": true
}

Example 7

Changes a user to a mailbox.

Request

{
  "credentials": {
    "user": "[email protected]",
    "password": "sw0rdf1sh"
  },
  "user":"[email protected]",
  "attributes":{
   "type":"mailbox",
   "delivery_local":true,
   "delivery_forward":false
  } 
}

Response

{
   "success": true
}

Example 8

Adds a note to a user

Request

{
  "credentials": {
    "user": "[email protected]",
    "password": "sw0rdf1sh"
  },
  "user":"[email protected]",
  "attributes":{
   "notes_external": "Premier customer.\nSpend extra time in support if they call.",
  } 
}

Response

{
   "success": true
}

Updated less than a minute ago

change_user


The change_user method creates a new user or changes the attributes of an existing user.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.