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 nameObligationDefinition/Value
companyRequiredThe 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 nameObligationDescription/Value
attributesReturned if company existsA list of the attributes and values associated with the company. For more information, see the Attributes table below.
errorReturned if success = falseA text string that explains the error.
error_numberReturned if success = falseA number that represents the error.
metadataReturned if company exists or can be createdAllowed values are: bulletins, createtime, default_password_encoding, inherit, and options.

For more information, see the Metadata table below.
settable_attributeReturned if company exists or can be createdThe 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.
successAlways returnedIndicates 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 nameObligationDefinition/Value
accountAlways returnedThe company name.
allowOptionalA list of senders whose messages are not scanned for spam; may include wildcards. For example [email protected] and *@example.com. Maximum 1000 addresses.
blockOptionalA 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.
brandOptionalThe default brand that is used for domains that do not have a brand assigned.
contactsOptionalA 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_encodingOptionalThe type of password hashing/encoding to be performed when OpenSRS receives an unencrypted password to store for a user.
domain_push_allowedOptionalA list of company_ids for resellers that are allowed to push domains to this company (see push_domain method)
domain_push_notifyOptionalAn email address notifications are sent to whenever a domain is pushed to this company (see push_domain method)
filterdeliveryOptionalThe 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.
languageOptionalThe default Webmail UI language for new domains in the company.
limit_aliasesOptionalThe maximum number of aliases that can be created for domains in this company.
limit_usersOptionalThe default maximum number of users that can be created in domains in this company.
notes_externalAlways returnedAny notes that were added through the change_company method. Maximum is 4096 characters. If there are no notes, returns null.
osrs_idOptionalThe OpenSRS Reseller ID associated with the company.
quotaOptionalThe default quota assigned to new domains created in this company, in megabytes (MB).
quota_maximumOptionalThe maximum quota (in Megabytes) that can be set for domains in this company.
password_strengthOptionalThe 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_passwordsOptionalIf 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_imap4OptionalThe default setting for new domains for the IMAP4 service (enabled, disabled, or suspended). If enabled, new users can log in via IMAP4.
service_pop3OptionalThe default setting for new domains for the POP3 service (enabled, disabled, or suspended). If enabled, new users can log in via POP3.
service_smtpinOptionalThe current default setting for new users for the SMTPIN service (enabled, disabled, or suspended). If enabled, new users can send email.
service_smtprelayOptionalThe default setting for new users for the SMTPRELAY service (enabled, disabled, or suspended).
service_smtprelay_webmailOptionalThe default setting for new users for the SMTPRELAY Webmail service (enabled, disabled, or suspended). If enabled, new users can send email via Webmail.
service_webmailOptionalThe default setting for new users for the Webmail service (enabled, disabled, or suspended). If enabled, new users can log in via Webmail.
smtp_sent_limitOptionalThe 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.
spamfolderOptionalThe 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.
spamheaderOptionalThe 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.
spamlevelOptionalThe level of aggressiveness for spam filtering if not set at the user or domain level. Allowed values are: Normal, High, and Very High.
spamtagOptionalThe 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_mailoutOptionalThe addresses to which company snapshots emails are sent for the company.
timezoneOptionalThe default timezone for domains in the company.
wm_domainaliasOptionalThe 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 nameObligationDescription/Value
bulletinsReturned if company existsA 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.
createtimeReturned if company existsThe date and time when the company was created, displayed in UNIX epoch time.
inheritReturned if company existsThe 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.
optionsReturned if company existsThe 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": [
     {