get_company

The get_company method retrieves settings and other information for a specified company.

Syntax

Request

{
    <credentials object>, 
    "company": <company name>

Response

{
    "success": true,
    "settable_attribute": [list of attribute names], 
    "metadata":
    {
        "options": {key value pairs} 
        "bulletins":
        {
         "manual": [{bulletin info}, {bulletin info}, ...],
         "auto": [{bulletin info}, {bulletin info}, ...]
         },
         "createtime": <company creation time> 
         "inherit": {
             "brand": <brand>, 
             "default_password_encoding": <encoding type>, 
             "filterdelivery": <quarantine | passthrough>, 
             "password_strength": <string>,
             "regen_passwords": <number>,
             "smtp_sent_limit": <number>,
             "spamfolder": <folder>,
             "spamheader":<header>,
             "spamtag": <tag>,
             "spamlevel": <level>
       } 
     },
     "attributes": {key value pairs}
}

Request fields for get_company

The following fields can be used in the get_company method:

Field name

Obligation

Definition/Value

company

Required

The company whose settings you want to view.

Response fields for get_company

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

Field name

Obligation

Description/Value

attributes

Returned if company exists

A list of the attributes and values associated with the company. For more information, see the Attributes table below.

error

Returned if success = false

A text string that explains the error.

error_number

Returned if success = false

A number that represents the error.

metadata

Returned if company exists or can be created

Allowed values are: bulletins, createtime, default_password_encoding, inherit, and options.

For more information, see the Metadata table below.

settable_attribute

Returned if company exists or can be created

The attributes that can be set and the services that can be enabled, disabled, or suspended. Allowed values are: allow, block, brand, contacts, default_password_encoding, filterdelivery, language, limit_aliases, limit_users, notes_external, quota, password_strength, regen_passwords, service_imap4, service_pop3, service_smtpin, service_smtprelay, service_smtprelay_webmail, service_webmail, spamfolder, spam_header, spamlevel, spamtag, stats_mailout, timezone, and wm_domainalias.

success

Always returned

Indicates whether the request was successful or not. Allowed values are true and false.


Attributes fields

The following fields may be returned within the attributes array.

Field name

Obligation

Definition/Value

account

Always returned

The company name.

allow

Optional

A list of senders whose messages are not scanned for spam; may include wildcards. For example [email protected] and *@example.com. Maximum 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 that is used for domains that do not have a brand assigned.

contacts

Optional

A list of up to 100 company contacts.

  • email — The contact's email address.

  • name — The contact's name; maximum 128 characters.

  • notes — Optional notes; maximum 1024 characters

  • phone — The contact's phone number; maximum 64 characters

  • type — The type of contact. Allowed values are business, technical, emergency, abuse, and billing.

default_password_encoding

Optional

The type of password hashing/encoding to be performed when OpenSRS receives an unencrypted password to store for a user.

domain_push_allowed

Optional

A list of company_ids for resellers that are allowed to push domains to this company (see push_domain method)

domain_push_notify

Optional

An email address notifications are sent to whenever a domain is pushed to this company (see push_domain method)

filterdelivery

Optional

The value that is used for domains in the company that do have this attribute set.

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.

language

Optional

The default Webmail UI language for new domains in the company.

limit_aliases

Optional

The maximum number of aliases that can be created for domains in this company.

limit_users

Optional

The default maximum number of users that can be created in domains in this company.

notes_external

Always returned

Any notes that were added through the change_company method. Maximum is 4096 characters. If there are no notes, returns null.

osrs_id

Optional

The OpenSRS Reseller ID associated with the company.

quota

Optional

The default quota assigned to new domains created in this company, in megabytes (MB).

quota_maximum

Optional

The maximum quota (in Megabytes) that can be set for domains in this company.

password_strength

Optional

The minimum level at which the password strength checks must pass (see change_user).

If set to null, the value will be inherited from the cluster default.

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

service_imap4

Optional

The default setting for new domains 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 domains for the POP3 service (enabled, disabled, or suspended). If enabled, new users can log in via POP3.

service_smtpin

Optional

The current 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 users in the company can send in a 24 hour period if this value is not set at the user or domain level.

Note: If the same message is sent to two recipients, it counts as two messages against this limit.

spamfolder

Optional

The folder to which messages that have been identified as spam are delivered if this value is not set at the user or domain level. Maximum 128 characters.

spamheader

Optional

The tag that will be assigned to the header of spam messages if not set at the user or domain level. 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 if not set at the user or domain level. Allowed values are: Normal, High, and Very High.

spamtag

Optional

The tag that is appended to an email message to identify spam if this value is not set at the user or domain level. Maximum 30 characters.

stats_mailout

Optional

The addresses to which company snapshots emails are sent for the company.

timezone

Optional

The default timezone for domains in the company.

wm_domainalias

Optional

The default value assigned to new domain in the company. If set to true, Webmail will offer users different From addresses based on domain aliases.

Metadata fields

The following fields may be returned in the metadata array:

Field name

Obligation

Description/Value

bulletins

Returned if company exists

A hash of the manual and auto bulletins that exist in the company. Includes the following:

  • count — The number of users to whom the bulletin was delivered.

  • last — The last time (date and time) that the bulletin was sent.

  • mtime — The last time that the bulletin was sent, in UNIX Epoch time.

  • name — The name of the bulletin.

  • total — The number of users to whom the bulletin is being sent.

Note: If the bulletin job has completed, the values for count and total will be the same.

createtime

Returned if company exists

The date and time when the company was created, displayed in UNIX epoch time.

inherit

Returned if company exists

The values that will be assigned if they are not explicity set for this company. Includes the following:

  • brand — The Webmail brand for this company.

  • default_password_encoding — The type of password hashing/encoding to be performed when OpenSRS receives an unencrypted password.

  • filterdelivery — The way in which spam messages are handled.

  • spamfolder — The folder into which messages identified as spam will be delivered.

  • spamheader — The tag that is added to messages that are identified as spam.

  • spamtag — The value of this field is prepended to the subject of any message that is identified as spam.

  • spamlevel — The level of aggressiveness set for the spam filter.

options

Returned if company exists

The list of settings that can be set or changed for the company. Includes all available values for each setting to allow a UI client to populate a page of attributes and drop-down options.

Allowed settings are brand, default_password_encoding, language, quota, spamlevel, and timezone.

For an explanation of each of these values, see the Attributes table above.

Examples for get_company

Request

{
  "credentials": {
"user": "[email protected]",
    "password": "sw0rdf1sh"
  },
  "company": "Example Corp"
}

Response

{
  "success": true,
  "settable_attributes": [
    "allow",
    "block",
    "brand",
    "contacts",
    "default_password_encoding”,
    "filterdelivery",
    "language",
    "limit_aliases",
    "limit_users",
    "notes_external",
    "quota",
    "regen_passwords”,
    "service_imap4",
    "service_pop3",
    "service_smtpin",
    "service_smtprelay",
    "service_smtprelay_webmail",
    "service_webmail",
    "spamfolder",
    "spamheader",
    "spamlevel",
    "spamtag",
    "stats_mailout",
    "timezone",
    "wm_domainalias"
    ],
"metadata": {
  "options": {
    "quota": [
      0,
      15360
    ],
    "quota_maximum": [
      0,
      1048576 
    ],
    "default_password_encoding": [
      null,
      "MD5",
      "SSHA224",
      "SSHA256",
      "SSHA384",
      "SSHA512",
      "BCRYPT-6",
      "BCRYPT-8",
      "BCRYPT-10",
      "BCRYPT-12"
  ],
    "timezone": [
    "Pacific/Wake",
  "Pacific/Niue",
  "Pacific/Honolulu",
  "America/Anchorage",
  "America/Vancouver",
  "America/Edmonton",
  "America/Phoenix",
  "America/Chicago",
  "America/Mexico_City",
  "America/Guatemala",
  "America/Montreal",
  "America/Havana",
  "America/Lima",
  "America/Caracas",
  "America/Halifax",
  "America/Asuncion",
  "America/Santiago",
  "America/Puerto_Rico",
  "America/La_Paz",
  "America/St_Johns",
  "America/Sao_Paulo",
  "America/Montevideo",
  "America/Buenos_Aires",
  "Atlantic/South_Georgia",
  "America/Noronha",
  "Atlantic/Azores",
  "Atlantic/Cape_Verde",
  "Europe/London",
  "Africa/Casablanca",
  "Atlantic/Reykjavik",
  "Europe/Amsterdam",
  "Africa/Algiers",
  "Asia/Beirut",
  "Europe/Helsinki",
  "Europe/Minsk",
  "Europe/Istanbul",
  "Asia/Amman",
  "Asia/Damascus",
  "Asia/Jerusalem",
  "Africa/Cairo",
  "Africa/Johannesburg",
  "Europe/Moscow",
  "Asia/Baghdad",
  "Asia/Tehran",
  "Asia/Baku",
  "Asia/Dubai",
  "Indian/Mauritius",
  "Asia/Kabul",
  "Asia/Karachi",
  "Asia/Colombo",
  "Asia/Calcutta",
  "Asia/Kathmandu",
  "Asia/Dhaka",
  "Asia/Rangoon",
  "Asia/Bangkok",
  "Asia/Phnom_Penh",
  "Asia/Hong_Kong",
  "Australia/Perth",
  "Asia/Tokyo",
  "Australia/Adelaide",
  "Australia/Darwin",
  "Australia/Melbourne",
  "Australia/Brisbane",
  "Australia/Lord_Howe",
  "Pacific/Guadalcanal",
  "Pacific/Norfolk",
  "Pacific/Fiji",
  "Pacific/Auckland",
  "Asia/Anadyr",
  "Pacific/Chatham",
   "Pacific/Tongatapu",
    "Pacific/Kiritimati"
  ],
  "language": [
    "el",
    "en",
    "es",
    "fr",
    "de",
    "it",
    "pt_BR",
    "nl",
    "da",
    "no",
    "sv"
   ], 
   "brand": [
     null,
     "Default Brand",
     "Demo Co Brand",
     "Demo Co Test Brand"
   ],
  "spamlevel": [
    null,
    "Very High",
    "High",
    "Normal"
   ] 
 },
"inherit": {
  "default_password_encoding": "BCRYPT-10", "spamfolder": ".Spam",
  "spamheader": null,
  "brand": "bcom1",
  "spamtag": null,
  "filterdelivery": "local",
  "spamlevel": "90"
 },
 "bulletins": {
   "manual": [],
   "auto": [
     {