{"_id":"56b25a3965ddf50d0076baa2","project":"569f9cf6650e1d1900f96b5b","__v":72,"githubsync":"","category":{"_id":"56b25826147e900d00d6497a","project":"569f9cf6650e1d1900f96b5b","version":"569f9cf6650e1d1900f96b5e","pages":["56b2583a9621f20d00efb31c","56b25a3965ddf50d0076baa2","56b2738894ab060d0006743c","56b4d1cf5f1cf00d00cc46d7","56b4f4e2b1a8690d00a59369","56b4f6925f1cf00d00cc4704","56b4fa3d5997532100bc6bcc","56b50ba8eed075230097d71e","56b5123585a6922300d1c506","56b51e475997532100bc6c08","56b5220b7719bb1900143055","56b524cc3d5f130d00dad1b8","56b5265b168b5c1700c15996","56b774438fb4420d006a618b","56b78012eb783a0d007894f3","56b78292a6c10c0d00a2d65d","56b7863aeb783a0d007894f8","56b78f68a6c10c0d00a2d66b","56b794566c2a240d0094ae8a","56b7a85dd22adc0d0053f4c2","56b7ac118fb4420d006a61b7"],"__v":21,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-03T19:42:30.051Z","from_sync":false,"order":7,"slug":"user-methods","title":"User methods"},"user":"5582e90181672a3900bb4fc7","version":{"_id":"569f9cf6650e1d1900f96b5e","project":"569f9cf6650e1d1900f96b5b","__v":12,"createdAt":"2016-01-20T14:43:02.785Z","releaseDate":"2016-01-20T14:43:02.785Z","categories":["569f9cf7650e1d1900f96b5f","56abdd81d4432d1900eed235","56abe0558beeff0d003b8118","56ad2f8b1c09150d00a183a8","56ad4e1cd21f1b0d00fd2f97","56b00ad88f7a4f0d0029dc92","56b2432e9621f20d00efb2bd","56b25826147e900d00d6497a","56b7af2a4b372d2100722c48","56b8c4d938b1070d0028920f","56b8cdab14feef0d0082415d","58599813cf9e112d0032cdab"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-03T19:51:21.769Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"## Syntax \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    <credentials object> \\n    \\\"user\\\": <name of user to create or change> \\n    \\\"attributes\\\":\\n     {\\n         <key-value pairs> \\n     }\\n     create_only: TRUE | FALSE\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Request fields for change_user\"\n}\n[/block]\nThe following fields can be used in the **change_user** method:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Definition/Value\",\n    \"0-0\": \"attributes\",\n    \"0-1\": \"Required\",\n    \"0-2\": \"The list of fields that you want to define or modify and their new values.\\n\\nFor more information, see the **Attributes** table below.\",\n    \"1-0\": \"create_only\",\n    \"1-1\": \"Optional\",\n    \"1-2\": \"Used 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.\",\n    \"2-0\": \"user\",\n    \"2-1\": \"Required\",\n    \"2-2\": \"The user that you want to create or modify.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n## Attributes fields \n\nYou can specify the following fields within the **attributes array**.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Definition/Value\",\n    \"0-0\": \"aliases\",\n    \"0-1\": \"Optional\",\n    \"0-2\": \"The list of alternate names for the account, for example, joe:::at:::example.com, joey@example.com, juser@example.com. 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\\n\\nThe maximum number of aliases is 2,000.\",\n    \"1-0\": \"allow\",\n    \"1-1\": \"Optional\",\n    \"1-2\": \"A list of email addresses on the user's allow list; may include wildcards. For example joe_goodguy@bigmail.com and *@example.com. Maximum is 1000 addresses.\",\n    \"2-0\": \"autoresponder\",\n    \"2-1\": \"Optional\",\n    \"2-2\": \"The text of the message that is automatically sent back to senders if **delivery_autoresponder** is set to **true**. Maximum size is 4,000 characters.\",\n    \"3-0\": \"autoresponder_ option_enddate\",\n    \"3-1\": \"Optional\",\n    \"3-2\": \"The date that the autoresponder expires, expressed in UNIX Epoch time. If not specified, the autoresponder never expires.\",\n    \"4-0\": \"autoresponder_option_interval\",\n    \"4-1\": \"Optional\",\n    \"4-2\": \"The 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.\",\n    \"5-0\": \"block\",\n    \"5-1\": \"Optional\",\n    \"5-2\": \"A list of email addresses on the user's block list; may include wildcards. For example, bob_thejerk@othermail.com and *@spammers- inc.com. Messages from these addresses will always be considered to be spam. Maximum is 1000 addresses.\",\n    \"6-0\": \"brand\",\n    \"6-1\": \"Optional\",\n    \"6-2\": \"The Webmail brand for this mailbox. If not specified, the account uses the domain setting.\",\n    \"7-0\": \"delivery_ autoresponder\",\n    \"7-1\": \"Optional\",\n    \"7-2\": \"If set to **true**, the configured auto response message is sent to the sender.\",\n    \"8-0\": \"delivery_filter\",\n    \"8-1\": \"Optional\",\n    \"8-2\": \"If set to true, messages are scanned and then passed to the domain's filtermx host; the messages are not stored locallly.\\n\\n**Note**: If **delivery_filter = true**, all other **delivery** attributes must be **false**.\",\n    \"9-0\": \"delivery_forward\",\n    \"9-1\": \"Optional\",\n    \"9-2\": \"If set to **true**, the message is forwarded to the mailbox's **forward_recipients** list.\",\n    \"10-0\": \"delivery_local\",\n    \"10-1\": \"Optional\",\n    \"10-2\": \"If set to **true**, the message is passed through the mailbox's sieve filters and stored locally.\",\n    \"33-0\": \"x\",\n    \"26-0\": \"x\"\n  },\n  \"cols\": 3,\n  \"rows\": 11\n}\n[/block]\nValid combinations of **delivery** attributes are\n\n  * **delivery_local**—Mail is stored locally.\n  * **delivery_local**, **delivery_forward**—Mail is stored locally and forwarded.\n  * **delivery_forward**—Mail is forwarded.\n  * **delivery_local**, **delivery_autoresponder**—Mail is stored locally, automatic reply sent.\n  * **delivery_local**, **delivery_forward**, **delivery_autoresponder**—Mail is stored locally and forwarded, automatic reply sent.\n  * ** delivery_forward**, **delivery_autoresponder**—Mail is forwarded, automatic reply sent.\n  * **delivery_filter**—Mail is forwarded to domain-defined mail host.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"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.\",\n  \"title\": \"Note:\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Definition/Value\",\n    \"0-0\": \"fax\",\n    \"0-1\": \"Optional\",\n    \"0-2\": \"The fax number for the account owner; can be a maximum of 30 characters.\",\n    \"1-0\": \"filterdelivery\",\n    \"1-1\": \"Optional\",\n    \"1-2\": \"Determines what happens to spam messages:\\n\\n  * **quarantine** — Spam messages are stored locally in the user's spam folder.\\n\\n  * **passthrough** — Spam messages are delivered with the specified spamtag and spamheader. \\n\\nIf not defined, the account uses the domain's **filterdelivery** setting.\",\n    \"2-0\": \"forward_option_restricted\",\n    \"2-1\": \"Optional\",\n    \"2-2\": \"If set to **true** and **delivery_forward** is also set to **true**, only messages from addresses on the forward recipients list are forwarded.\",\n    \"3-0\": \"forward_option_subject_prefix\",\n    \"3-1\": \"Optional\",\n    \"3-2\": \"If **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\",\n    \"4-0\": \"forward_option_reply_to\",\n    \"4-1\": \"Optional\",\n    \"4-2\": \"If **delivery_forward** is set to **true**, this email address is added to the **Reply-To** header of forwarded messages.\",\n    \"5-0\": \"forward_ recipients\",\n    \"5-1\": \"Optional\",\n    \"5-2\": \"If **delivery_forward** is set to **true**, incoming messages will be forwarded to this list of addresses. Maximum number of addresses is 1,000.\",\n    \"6-0\": \"language\",\n    \"6-1\": \"Optional\",\n    \"6-2\": \"The default language in which the mailbox will be displayed. May be overridden by the user.\\n\\nA list of valid language names is displayed in the **metadata ->options** field in the [get_user](https://api-opensrs-email.readme.io/v1.0/docs/get_user?bypass=8272e34bb5)  response.\",\n    \"7-0\": \"macsettings\",\n    \"7-1\": \"Optional\",\n    \"7-2\": \"A string that contains the user's MAC UI preferences. Only used by the MAC; not recommended for use by other applications. Maximum 2048 characters.\",\n    \"8-0\": \"max_pab_entries\",\n    \"8-1\": \"Optional\",\n    \"8-2\": \"The maximum number of entries (contacts and groups) that the user can have in their address book.\",\n    \"9-0\": \"name\",\n    \"9-1\": \"Optional\",\n    \"9-2\": \"The name that is used in the From field of email messages. The format is UTF-8 text and can be up to 512 characters.\",\n    \"10-0\": \"notes_external\",\n    \"10-1\": \"Optional\",\n    \"10-2\": \"Any notes you want to add to the user. Maximum is 4096 characters.\",\n    \"11-0\": \"password\",\n    \"11-1\": \"Optional\",\n    \"11-2\": \"The password used to log in to all services. \\n\\nHere are the constraints are requirements for passwords:\\n\\n* Can be plain text or hashed.\\n  * If plain text, the text can be **between 1 and 54 characters** (Length must not exceed 54 characters). \\n  * If hashed, it is a ASCII string consisting of an hash type in curly braces followed by 1 to 150 characters.\\n  * 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). \\n  * Passwords are always stored and retrieved hashed. If a plain text password is assigned, it will be hashed before it is stored.\\n  * The only characters that can be used are ASCII characters with the decimal codes 33 and 35 to 126.\\n  * An empty password is not allowed.\\n  * 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: ~ ! @ $ % ^ & * ( ) - _ = + / \\\\ ] [ { } : ; > < , . ‘ | ? #\\n  * 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) \\n  * Double quotation marks are not allowed (ASCII character 34). Delete (ASCII character 127) is not allowed. Space (ASCII character 32) is not allowed.\\n\\nSee section on Password Validation, below.\",\n    \"12-0\": \"phone\",\n    \"12-1\": \"Optional\",\n    \"12-2\": \"The user's phone number; maximum 30 characters.\",\n    \"13-0\": \"quota\",\n    \"13-1\": \"Optional\",\n    \"13-2\": \"The maximum amount of storage (in bytes) that the mailbox may use, including mail and file storage.\",\n    \"14-0\": \"reject_spam\",\n    \"14-1\": \"Optional\",\n    \"14-2\": \"Determines whether spam messages are rejected at the SMTP level. Allowed values are **true** and **false**.\",\n    \"15-0\": \"service_imap4\",\n    \"15-1\": \"Optional\",\n    \"15-2\": \"The setting for the IMAP4 service (**enabled**, **disabled**, or **suspended**). If **enabled**, the user can log in via IMAP4.\",\n    \"16-0\": \"service_pop3\",\n    \"16-1\": \"Optional\",\n    \"16-2\": \"The setting for the POP3 service (**enabled**, **disabled**, or **suspended**). If **enabled**, the user can log in via POP3.\",\n    \"17-0\": \"service_smtpin\",\n    \"17-1\": \"Optional\",\n    \"17-2\": \"The setting for the SMTPIN service (enabled, disabled, or suspended). If enabled, the user can send email.\",\n    \"18-0\": \"service_smtprelay\",\n    \"18-1\": \"Optional\",\n    \"18-2\": \"The setting for the SMTPRELAY service (**enabled**, **disabled**, or **suspended**).\",\n    \"19-0\": \"service_smtprelay_web mail\",\n    \"19-1\": \"Optional\",\n    \"19-2\": \"The setting for the SMTPRELAY Webmail service (enabled, disabled, or suspended). If enabled, the user can send email via Webmail.\",\n    \"20-0\": \"service_webmail\",\n    \"20-1\": \"Optional\",\n    \"20-2\": \"The setting for the Webmail service (**enabled**, webmail **disabled**, or **suspended**). If **enabled**, the user\\ncan log in via Webmail.\"\n  },\n  \"cols\": 3,\n  \"rows\": 21\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Password Validation\",\n  \"body\": \"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.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"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).\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Definition/Value\",\n    \"0-0\": \"sieve\",\n    \"0-1\": \"Optional\",\n    \"0-2\": \"The user's sieve filters.\",\n    \"1-0\": \"smtp_sent_limit\",\n    \"1-1\": \"Optional\",\n    \"1-2\": \"The 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.\\n\\n**Note**: If the same message is sent to two recipients, it counts as two messages against this limit.\",\n    \"2-0\": \"spamfolder\",\n    \"2-1\": \"Optional\",\n    \"2-2\": \"The 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.\",\n    \"3-0\": \"spamheader\",\n    \"3-1\": \"Optional\",\n    \"3-2\": \"The tag that is added to messages that are identified as spam. Maximum 512 characters.\",\n    \"4-0\": \"spamlevel\",\n    \"4-1\": \"Optional\",\n    \"4-2\": \"The 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.\",\n    \"5-0\": \"spamtag\",\n    \"5-1\": \"Optional\",\n    \"5-2\": \"The 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.\\n\\n**Note**: This value is not supported for filteronly accounts.\",\n    \"6-0\": \"timezone\",\n    \"6-1\": \"Optional\",\n    \"6-2\": \"The timezone that the mailbox will use.\\n\\nA list of valid timezones is displayed in the metadata ->options field in the [get_user](https://api-opensrs-email.readme.io/v1.0/docs/get_user?bypass=8272e34bb5) response.\",\n    \"7-0\": \"title\",\n    \"7-1\": \"Optional\",\n    \"7-2\": \"The user's job title;maximum 60 characters.\",\n    \"8-0\": \"type\",\n    \"8-1\": \"Optional\",\n    \"8-2\": \"Determines 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.\\n\\nThe 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.\",\n    \"9-0\": \"workgroup\",\n    \"9-1\": \"Optional\",\n    \"9-2\": \"The workgroup to which the user belongs.\"\n  },\n  \"cols\": 3,\n  \"rows\": 10\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response fields for change_user\"\n}\n[/block]\nThe following fields may be returned in response to the **change_user** method:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Description/Value\",\n    \"0-0\": \"error\",\n    \"0-1\": \"Returned if **success = false**\",\n    \"0-2\": \"A text string that explains the error.\",\n    \"1-0\": \"error_number\",\n    \"1-1\": \"Returned if **success = false**\",\n    \"1-2\": \"A number that represents the error.\",\n    \"2-0\": \"hints\",\n    \"2-1\": \"May by returned when **success = false**\",\n    \"2-2\": \"A list of the attributes that had errors and the reason for each error.\",\n    \"3-0\": \"success\",\n    \"3-1\": \"Always returned\",\n    \"3-2\": \"Indicates whether the request was successful or not. Allowed values are **true** and **false**.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples for change_user\"\n}\n[/block]\n## Example 1\n\nSuccessfully creates a new user.\n\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n\\t\\t\\\"user\\\": \\\"domain_admin@example.com\\\",\\n    \\\"password\\\": \\\"sw0rdf1sh\\\"\\n  },\\n  \\\"user\\\": \\\"bhayden@example.com\\\",\\n  \\\"attributes\\\": {\\n    \\\"name\\\": \\\"Bob Hayden\\\",\\n    \\\"password\\\": \\\"changeit\\\",\\n    \\\"delivery_forward\\\": true,\\n    \\\"forward_recipients\\\": [\\n        \\\"bob.hayden@example.com\\n  }\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"success\\\": true\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Example 2\n\nChanges the user's spamtag attribute.\n\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n    \\\"user\\\": \\\"domain_admin@example.com\\\",\\n    \\\"password\\\": \\\"sw0rdf1sh\\\"\\n  },\\n  \\\"user\\\": \\\"bhayden@example.com\\\",\\n  \\\"attributes\\\": {\\n    \\\"spamtag\\\": \\\"[JUNK]\\\"\\n  }\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"success\\\": true\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Example 3\n\nAttempts to modify an existing user, but fails due to badly formatted attributes.\n\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n\\t\\t\\\"user\\\": \\\"domain_admin@example.com\\\",\\n    \\\"password\\\": \\\"sw0rdf1sh\\\"\\n  },\\n   \\\"user\\\": \\\"robson@example.com\\\",\\n   \\\"attributes\\\": {\\n      \\\"spamtag\\\": \\\"(SPAM)\\\",\\n      \\\"name\\\": [\\n\\t\\t\\t\\t \\\"Robson\\\",\\n\\t\\t\\t\\t \\\"Wilk\\\" \\n      ],\\n      \\\"allow\\\": \\\"Mom@Userfamily.xom\\\",\\n      \\\"block\\\": [\\n         \\\"spammers@badguys.org\\\",\\n         \\\"*@naughty.edu\\\"\\n      ]\\n\\t } \\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"success\\\": false\\n   \\\"hints\\\": {\\n      \\\"name\\\": \\\"Not a valid Text[1-512] (not a string)\\\",\\n      \\\"allow\\\": \\\"Not a list\\\"\\n   },\\n   \\\"error_number\\\": 6,\\n   \\\"error\\\": \\\"One or more attributes badly formatted\\\" \\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Example 4\n\nAttempts to create a user that already exists (with **create_only** flag).\n\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n  \\\"user\\\": \\\"domain_admin@example.com\\\",\\n    \\\"password\\\": \\\"sw0rdf1sh\\\"\\n  },\\n  \\\"user\\\":\\\"bhayden@example.com\\\",\\n  \\\"create_only\\\":true,\\n  \\\"attributes\\\":{\\n    \\\"type\\\":\\\"mailbox\\\",\\n    \\\"password\\\":\\\"gob\\\",\\n    \\\"reject_spam\\\":false,\\n    \\\"name\\\":\\\"Bob Hayden\\\",\\n    \\\"workgroup\\\":\\\"staff\\\"\\n  } \\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"success\\\":false,\\n  \\\"error_number\\\":23,\\n  \\\"error\\\":\\\"Object already exists\\\",\\n  \\\"audit\\\":\\\"jewel30_50c235f127\\\"\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Example 5\n\nChanges a user to a filter.\n\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n    \\\"user\\\": \\\"domain_admin@example.com\\\", \\n    \\\"password\\\": \\\"sw0rdf1sh\\\"\\n    },\\n    \\\"user\\\":\\\"bhayden@example.com\\\",\\n    \\\"attributes\\\":{\\n      \\\"type\\\":\\\"filter\\\"\\n    }\\n}\\n\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"success\\\": true\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Example 6\n\nChanges a user to a forward.\n\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n    \\\"user\\\": \\\"domain_admin@example.com\\\",\\n    \\\"password\\\": \\\"sw0rdf1sh\\\"\\n  },\\n  \\\"user\\\":\\\"bhayden@example.com\\\",\\n  \\\"attributes\\\":{\\n    \\\"type\\\":\\\"forward\\\"\\n  }\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"success\\\": true\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Example 7\n\nChanges a user to a mailbox.\n\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n    \\\"user\\\": \\\"domain_admin@example.com\\\",\\n    \\\"password\\\": \\\"sw0rdf1sh\\\"\\n  },\\n  \\\"user\\\":\\\"bhayden@example.com\\\",\\n  \\\"attributes\\\":{\\n   \\\"type\\\":\\\"mailbox\\\",\\n   \\\"delivery_local\\\":true,\\n   \\\"delivery_forward\\\":false\\n  } \\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"success\\\": true\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Example 8\n\nAdds a note to a user\n\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n    \\\"user\\\": \\\"domain_admin@example.com\\\",\\n    \\\"password\\\": \\\"sw0rdf1sh\\\"\\n  },\\n  \\\"user\\\":\\\"bhayden@example.com\\\",\\n  \\\"attributes\\\":{\\n   \\\"notes_external\\\": \\\"Premier customer.\\\\nSpend extra time in support if they call.\\\",\\n  } \\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"success\\\": true\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]","excerpt":"The **change_user** method creates a new user or changes the attributes of an existing user.","slug":"change_user","type":"basic","title":"change_user"}

change_user

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

## Syntax [block:code] { "codes": [ { "code": "{\n <credentials object> \n \"user\": <name of user to create or change> \n \"attributes\":\n {\n <key-value pairs> \n }\n create_only: TRUE | FALSE\n}", "language": "perl", "name": " " } ] } [/block] [block:api-header] { "type": "basic", "title": "Request fields for change_user" } [/block] The following fields can be used in the **change_user** method: [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Definition/Value", "0-0": "attributes", "0-1": "Required", "0-2": "The list of fields that you want to define or modify and their new values.\n\nFor more information, see the **Attributes** table below.", "1-0": "create_only", "1-1": "Optional", "1-2": "Used 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.", "2-0": "user", "2-1": "Required", "2-2": "The user that you want to create or modify." }, "cols": 3, "rows": 3 } [/block] ## Attributes fields You can specify the following fields within the **attributes array**. [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Definition/Value", "0-0": "aliases", "0-1": "Optional", "0-2": "The list of alternate names for the account, for example, joe@example.com, joey@example.com, juser@example.com. 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\n\nThe maximum number of aliases is 2,000.", "1-0": "allow", "1-1": "Optional", "1-2": "A list of email addresses on the user's allow list; may include wildcards. For example joe_goodguy@bigmail.com and *@example.com. Maximum is 1000 addresses.", "2-0": "autoresponder", "2-1": "Optional", "2-2": "The text of the message that is automatically sent back to senders if **delivery_autoresponder** is set to **true**. Maximum size is 4,000 characters.", "3-0": "autoresponder_ option_enddate", "3-1": "Optional", "3-2": "The date that the autoresponder expires, expressed in UNIX Epoch time. If not specified, the autoresponder never expires.", "4-0": "autoresponder_option_interval", "4-1": "Optional", "4-2": "The 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.", "5-0": "block", "5-1": "Optional", "5-2": "A list of email addresses on the user's block list; may include wildcards. For example, bob_thejerk@othermail.com and *@spammers- inc.com. Messages from these addresses will always be considered to be spam. Maximum is 1000 addresses.", "6-0": "brand", "6-1": "Optional", "6-2": "The Webmail brand for this mailbox. If not specified, the account uses the domain setting.", "7-0": "delivery_ autoresponder", "7-1": "Optional", "7-2": "If set to **true**, the configured auto response message is sent to the sender.", "8-0": "delivery_filter", "8-1": "Optional", "8-2": "If set to true, messages are scanned and then passed to the domain's filtermx host; the messages are not stored locallly.\n\n**Note**: If **delivery_filter = true**, all other **delivery** attributes must be **false**.", "9-0": "delivery_forward", "9-1": "Optional", "9-2": "If set to **true**, the message is forwarded to the mailbox's **forward_recipients** list.", "10-0": "delivery_local", "10-1": "Optional", "10-2": "If set to **true**, the message is passed through the mailbox's sieve filters and stored locally.", "33-0": "x", "26-0": "x" }, "cols": 3, "rows": 11 } [/block] 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. [block:callout] { "type": "info", "body": "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.", "title": "Note:" } [/block] [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Definition/Value", "0-0": "fax", "0-1": "Optional", "0-2": "The fax number for the account owner; can be a maximum of 30 characters.", "1-0": "filterdelivery", "1-1": "Optional", "1-2": "Determines what happens to spam messages:\n\n * **quarantine** — Spam messages are stored locally in the user's spam folder.\n\n * **passthrough** — Spam messages are delivered with the specified spamtag and spamheader. \n\nIf not defined, the account uses the domain's **filterdelivery** setting.", "2-0": "forward_option_restricted", "2-1": "Optional", "2-2": "If set to **true** and **delivery_forward** is also set to **true**, only messages from addresses on the forward recipients list are forwarded.", "3-0": "forward_option_subject_prefix", "3-1": "Optional", "3-2": "If **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", "4-0": "forward_option_reply_to", "4-1": "Optional", "4-2": "If **delivery_forward** is set to **true**, this email address is added to the **Reply-To** header of forwarded messages.", "5-0": "forward_ recipients", "5-1": "Optional", "5-2": "If **delivery_forward** is set to **true**, incoming messages will be forwarded to this list of addresses. Maximum number of addresses is 1,000.", "6-0": "language", "6-1": "Optional", "6-2": "The default language in which the mailbox will be displayed. May be overridden by the user.\n\nA list of valid language names is displayed in the **metadata ->options** field in the [get_user](https://api-opensrs-email.readme.io/v1.0/docs/get_user?bypass=8272e34bb5) response.", "7-0": "macsettings", "7-1": "Optional", "7-2": "A string that contains the user's MAC UI preferences. Only used by the MAC; not recommended for use by other applications. Maximum 2048 characters.", "8-0": "max_pab_entries", "8-1": "Optional", "8-2": "The maximum number of entries (contacts and groups) that the user can have in their address book.", "9-0": "name", "9-1": "Optional", "9-2": "The name that is used in the From field of email messages. The format is UTF-8 text and can be up to 512 characters.", "10-0": "notes_external", "10-1": "Optional", "10-2": "Any notes you want to add to the user. Maximum is 4096 characters.", "11-0": "password", "11-1": "Optional", "11-2": "The password used to log in to all services. \n\nHere are the constraints are requirements for passwords:\n\n* Can be plain text or hashed.\n * If plain text, the text can be **between 1 and 54 characters** (Length must not exceed 54 characters). \n * If hashed, it is a ASCII string consisting of an hash type in curly braces followed by 1 to 150 characters.\n * 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). \n * Passwords are always stored and retrieved hashed. If a plain text password is assigned, it will be hashed before it is stored.\n * The only characters that can be used are ASCII characters with the decimal codes 33 and 35 to 126.\n * An empty password is not allowed.\n * 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: ~ ! @ $ % ^ & * ( ) - _ = + / \\ ] [ { } : ; > < , . ‘ | ? #\n * 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) \n * Double quotation marks are not allowed (ASCII character 34). Delete (ASCII character 127) is not allowed. Space (ASCII character 32) is not allowed.\n\nSee section on Password Validation, below.", "12-0": "phone", "12-1": "Optional", "12-2": "The user's phone number; maximum 30 characters.", "13-0": "quota", "13-1": "Optional", "13-2": "The maximum amount of storage (in bytes) that the mailbox may use, including mail and file storage.", "14-0": "reject_spam", "14-1": "Optional", "14-2": "Determines whether spam messages are rejected at the SMTP level. Allowed values are **true** and **false**.", "15-0": "service_imap4", "15-1": "Optional", "15-2": "The setting for the IMAP4 service (**enabled**, **disabled**, or **suspended**). If **enabled**, the user can log in via IMAP4.", "16-0": "service_pop3", "16-1": "Optional", "16-2": "The setting for the POP3 service (**enabled**, **disabled**, or **suspended**). If **enabled**, the user can log in via POP3.", "17-0": "service_smtpin", "17-1": "Optional", "17-2": "The setting for the SMTPIN service (enabled, disabled, or suspended). If enabled, the user can send email.", "18-0": "service_smtprelay", "18-1": "Optional", "18-2": "The setting for the SMTPRELAY service (**enabled**, **disabled**, or **suspended**).", "19-0": "service_smtprelay_web mail", "19-1": "Optional", "19-2": "The setting for the SMTPRELAY Webmail service (enabled, disabled, or suspended). If enabled, the user can send email via Webmail.", "20-0": "service_webmail", "20-1": "Optional", "20-2": "The setting for the Webmail service (**enabled**, webmail **disabled**, or **suspended**). If **enabled**, the user\ncan log in via Webmail." }, "cols": 3, "rows": 21 } [/block] [block:callout] { "type": "info", "title": "Password Validation", "body": "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." } [/block] [block:callout] { "type": "info", "body": "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)." } [/block] [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Definition/Value", "0-0": "sieve", "0-1": "Optional", "0-2": "The user's sieve filters.", "1-0": "smtp_sent_limit", "1-1": "Optional", "1-2": "The 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.\n\n**Note**: If the same message is sent to two recipients, it counts as two messages against this limit.", "2-0": "spamfolder", "2-1": "Optional", "2-2": "The 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.", "3-0": "spamheader", "3-1": "Optional", "3-2": "The tag that is added to messages that are identified as spam. Maximum 512 characters.", "4-0": "spamlevel", "4-1": "Optional", "4-2": "The 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.", "5-0": "spamtag", "5-1": "Optional", "5-2": "The 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.\n\n**Note**: This value is not supported for filteronly accounts.", "6-0": "timezone", "6-1": "Optional", "6-2": "The timezone that the mailbox will use.\n\nA list of valid timezones is displayed in the metadata ->options field in the [get_user](https://api-opensrs-email.readme.io/v1.0/docs/get_user?bypass=8272e34bb5) response.", "7-0": "title", "7-1": "Optional", "7-2": "The user's job title;maximum 60 characters.", "8-0": "type", "8-1": "Optional", "8-2": "Determines 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.\n\nThe 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.", "9-0": "workgroup", "9-1": "Optional", "9-2": "The workgroup to which the user belongs." }, "cols": 3, "rows": 10 } [/block] [block:api-header] { "type": "basic", "title": "Response fields for change_user" } [/block] The following fields may be returned in response to the **change_user** method: [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Description/Value", "0-0": "error", "0-1": "Returned if **success = false**", "0-2": "A text string that explains the error.", "1-0": "error_number", "1-1": "Returned if **success = false**", "1-2": "A number that represents the error.", "2-0": "hints", "2-1": "May by returned when **success = false**", "2-2": "A list of the attributes that had errors and the reason for each error.", "3-0": "success", "3-1": "Always returned", "3-2": "Indicates whether the request was successful or not. Allowed values are **true** and **false**." }, "cols": 3, "rows": 4 } [/block] [block:api-header] { "type": "basic", "title": "Examples for change_user" } [/block] ## Example 1 Successfully creates a new user. **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n\t\t\"user\": \"domain_admin@example.com\",\n \"password\": \"sw0rdf1sh\"\n },\n \"user\": \"bhayden@example.com\",\n \"attributes\": {\n \"name\": \"Bob Hayden\",\n \"password\": \"changeit\",\n \"delivery_forward\": true,\n \"forward_recipients\": [\n \"bob.hayden@example.com\n }\n}", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"success\": true\n}", "language": "perl", "name": " " } ] } [/block] ## Example 2 Changes the user's spamtag attribute. **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n \"user\": \"domain_admin@example.com\",\n \"password\": \"sw0rdf1sh\"\n },\n \"user\": \"bhayden@example.com\",\n \"attributes\": {\n \"spamtag\": \"[JUNK]\"\n }\n}", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"success\": true\n}", "language": "perl", "name": " " } ] } [/block] ## Example 3 Attempts to modify an existing user, but fails due to badly formatted attributes. **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n\t\t\"user\": \"domain_admin@example.com\",\n \"password\": \"sw0rdf1sh\"\n },\n \"user\": \"robson@example.com\",\n \"attributes\": {\n \"spamtag\": \"(SPAM)\",\n \"name\": [\n\t\t\t\t \"Robson\",\n\t\t\t\t \"Wilk\" \n ],\n \"allow\": \"Mom@Userfamily.xom\",\n \"block\": [\n \"spammers@badguys.org\",\n \"*@naughty.edu\"\n ]\n\t } \n}", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"success\": false\n \"hints\": {\n \"name\": \"Not a valid Text[1-512] (not a string)\",\n \"allow\": \"Not a list\"\n },\n \"error_number\": 6,\n \"error\": \"One or more attributes badly formatted\" \n}", "language": "perl", "name": " " } ] } [/block] ## Example 4 Attempts to create a user that already exists (with **create_only** flag). **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n \"user\": \"domain_admin@example.com\",\n \"password\": \"sw0rdf1sh\"\n },\n \"user\":\"bhayden@example.com\",\n \"create_only\":true,\n \"attributes\":{\n \"type\":\"mailbox\",\n \"password\":\"gob\",\n \"reject_spam\":false,\n \"name\":\"Bob Hayden\",\n \"workgroup\":\"staff\"\n } \n}", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"success\":false,\n \"error_number\":23,\n \"error\":\"Object already exists\",\n \"audit\":\"jewel30_50c235f127\"\n}", "language": "perl", "name": " " } ] } [/block] ## Example 5 Changes a user to a filter. **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n \"user\": \"domain_admin@example.com\", \n \"password\": \"sw0rdf1sh\"\n },\n \"user\":\"bhayden@example.com\",\n \"attributes\":{\n \"type\":\"filter\"\n }\n}\n", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"success\": true\n}", "language": "perl", "name": " " } ] } [/block] ## Example 6 Changes a user to a forward. **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n \"user\": \"domain_admin@example.com\",\n \"password\": \"sw0rdf1sh\"\n },\n \"user\":\"bhayden@example.com\",\n \"attributes\":{\n \"type\":\"forward\"\n }\n}", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"success\": true\n}", "language": "perl", "name": " " } ] } [/block] ## Example 7 Changes a user to a mailbox. **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n \"user\": \"domain_admin@example.com\",\n \"password\": \"sw0rdf1sh\"\n },\n \"user\":\"bhayden@example.com\",\n \"attributes\":{\n \"type\":\"mailbox\",\n \"delivery_local\":true,\n \"delivery_forward\":false\n } \n}", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"success\": true\n}", "language": "perl", "name": " " } ] } [/block] ## Example 8 Adds a note to a user **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n \"user\": \"domain_admin@example.com\",\n \"password\": \"sw0rdf1sh\"\n },\n \"user\":\"bhayden@example.com\",\n \"attributes\":{\n \"notes_external\": \"Premier customer.\\nSpend extra time in support if they call.\",\n } \n}", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"success\": true\n}", "language": "perl", "name": " " } ] } [/block]