change_domain

Syntax

{
    <credentials object>, 
    "domains": <domain> 
    "attributes":
      {
        <key value pairs>
      }, 
   }
}

Request fields for change_domain

Request fields for change_domain method:

Field name	Obligation	Definition/Value
attributes	Required	The list of fields that you want to configure and their values. For more information, see the Attributes table below.
create_only	Optional	Used to prevent changes to existing domains. If set to true and the specified domain exists, the domain will not be modified and an error will be returned.
domain	Required	The domain that you want to create or change.

Field name

Obligation

Definition/Value

attributes

Required

The list of fields that you want to configure and their values.

For more information, see the Attributes table below.

create_only

Optional

Used to prevent changes to existing domains. If set to true and the specified domain exists, the domain will not be modified and an error will be returned.

domain

Required

The domain that you want to create or change.

Attributes fields

You can specify the following fields within the attributes array.

Field name	Obligation	Definition/Value
aliases	Optional	A list of alternate names for the domain. Users in the domain can receive mail that is sent to an alias domain. For example, if example- corporation.com is an alias for example.com, so mail that is sent to joe_user@example- corporation.com will be delivered to [email protected] The maximum number of aliases is 2000.
allow	Optional	A list of senders whose messages are not scanned for spam; may include wildcards. For example [email protected] and *@example.com. Maximum is 1000 addresses.
block	Optional	A list of email addresses whose messages will always be identified as spam; 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.
brand	Optional	The default brand used for mailboxes in the domain. If undefined, the company brand is used.
catchall	Optional	If set, any mail sent to a mailbox in the domain that does not exist will be sent to the specified mailbox. Note*: This feature cannot be enabled for new domains.
company	Optional*	Used to reassign the domain to another company the admin controls. Should be a string; the name of the receiving company. See the notes on domain reassignment below.
default_ password_encoding	Optional	The type of password hashing/encoding to be performed when OpenSRS receives an unencrypted password to store for a user. We recommend BCRYPT encoding.
disabled	Optional	If set to true, mailboxes in the domain will not function.
filterdelivery	Optional	The way in which spam messages are handled by the OpenSRS email filter. Allowed values are: quarantine — Spam messages are stored locally in the user's spam folder. passthrough — Spam messages are delivered with the specified spamtag and spamheader. If undefined, the company's value is used.
filtermx	Optional	The mail server (and optionally, SMTP port) to which messages received by filter users in this domain are sent after spam and virus scanning.
language	Optional	The default Webmail UI language for new users in the domain. May be overridden by the user. A list of valid languages is displayed in the metadata ->options field in the get_domain response.
limit_aliases	Optional	The maximum number of aliases that can be created for mailboxes in the domain. If this number is less than the number of aliases currently in the domain, no new aliases can be created. If not defined, any number of aliases can be created.
limit_users	Optional	The maximum number of users that can be created in the domain. If this number is less than the number of users currently in the domain, no new users can be created. If undefined, any number of users can be created.
notes_external	Optional	Any notes you want to add to the domain. Maximum is 4096 characters.
quota	Optional	The default maximum amount of storage (in bytes) that new mailboxes may use, including mail and file storage.
quota_maximum	Optional	The default maximum quota (in Megabytes) that can be assigned to any mailbox in the domain.
regen_passwords	Optional	If set to true, the next time a user logs in, their passwords will be converted to the encoding specified in default_password_encoding (if their current encoding differs from the one specified in default_password_encoding).
password_strength	Optional	The minimum level at which the password strength checks must pass (see change_user). Valid values are null, "weak", "medium", "good", and "strong". If set to null, the value will be inherited from the company level.
service_imap4	Optional	The default setting for new users for the IMAP4 service (enabled, disabled, or suspended). If enabled, new users can log in via IMAP4.
service_pop3	Optional	The default setting for new users for the POP3 service (enabled, disabled, or suspended). If enabled, new users can log in via POP3.
service_smtpin	Optional	The default setting for new users for the SMTPIN service (enabled, disabled, or suspended). If enabled, new users can send email.
service_ smtprelay	Optional	The default setting for new users for the SMTPRELAY service (enabled, disabled, or suspended).
service_smtprelay_webmail	Optional	The default setting for new users for the SMTPRELAY Webmail service (enabled, disabled, or suspended). If enabled, new users can send email via Webmail.
service_webmail	Optional	The default setting for new users for the Webmail service (enabled, disabled, or suspended). If enabled, new users can log in via Webmail.
smtp_sent_limit	Optional	The default maximum number of messages that the user can send in a 24 hour period. Maximum number is 10,000. If not defined, the company's smtp_sent_limit is used.
spamfolder	Optional	The folder to which messages that have been identified as spam are delivered. Maximum 128 characters.
spamheader	Optional	The tag that will be assigned to the header of spam messages. The format for the header must be [Capital letter]anything[:] anything. For example, XSpam: Spam detected. Maximum 512 characters.
spamlevel	Optional	The level of aggressiveness for spam filtering. Allowed values are: Normal, High, and Very High.
spamtag	Optional	The tag that is appended to an email message to identify it as spam. Maximum 30 characters.
timezone	Optional	The default Webmail UI timezone for users in this domain. A list of valid timezones is displayed in the metadata ->options field in the get_domain response.
wm_domainalias	Optional	If set to true, Webmail will offer users different From addresses based on domain aliases.
workgroup	Optional	The default workgroup to which new accounts in the domain will belong.

📘
Domain Reassignment
Company admins may be configured to control multiple Companies. Currently, you must request that OpenSRS set this up for you - both companies must be controlled by the same billing entity.
Once set up, the company names you can reassign to will be included in the extra_info.roles section of the authenticate response.
It may be wise to always reset the brand to null before or during the domain reassignment, as the current brand will not be under the receiving company. If set at the domain level, the current brand will continue to work after reassignment, but it may cause confusion to anyone looking at the domain in the future.

Response fields for change_domain

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

Field name	Field name	Description/Value
error	Returned if success = false	A text string that explains the error.
error_number	Returned if success = false	A number that represents the error.
hints	Returned if success = false	Lists one or more attributes that had errors and suggests a possible cause of each error.
success	Always returned	Indicates whether the request was successful or not. Allowed values are true and false.

Examples for change_domain

Example 1

Changes the allow attribute.

Request

{
  "credentials": {
    "user": "[email protected]",
    "password": "sw0rdf1sh"
  },
  "domain": "example.com",
  "attributes": {
    "allow": [
      "*@example.com",
      "[email protected]"
    ] 
  }
}

Response

{
    "success": true
}

Example 2

Adds a note to the domain

Request

{
  "credentials": {
    "user": "[email protected]",
    "password": "sw0rdf1sh"
  },
  "domain": "example.com",
  "attributes": {
    "notes_external: "Has not paid.\nDo NOT enable without consulting 
Finance."
  } 
}

Response

{
    "success": true
}

Example 3

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

Request

{
  "attributes":{},
  "domain":"gob.com",
  "create_only":true,
  "credentials":{...}
}

Response

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

Syntax

Request fields for change_domain

Attributes fields

📘Domain Reassignment

Response fields for change_domain

Examples for change_domain

Example 1

Example 2

Example 3

📘
Domain Reassignment