| The User Preference API can be used to verify whether a mail user preference configuration exists and to create one if required. This article explains how to perform these operations using the FortiMail REST API. Note: The procedure to configure secondary account mapping using the UserMaillist API is covered in Technical Tip: Create a safelist, blocklist and secondary account for a particular mail user via API. This article focuses only on the User Preference API logic. Please refer to the existing secondary mapping KB for mapping configuration details. A User Preference object is not automatically initialized for every mailbox. - When using the API, it is therefore important to:
- Verify whether the User Preference object already exists.
- Initialize it only if it has not yet been created.
- Review configuration parameters such as safelist, blocklist, or secondary account after confirming existence.
- How to check if a user preference exists:
curl -k -X GET https://<FortiMail-IP>/api/v1/UserPreference/<user@example.com>/ \ -b cookies.txt \ -H "Content-Type: application/json"
Example response - existing user: { "objectID": "UserPreference:maydin@test.com{D:test.com}", "mdomain": "test.com", "mkey": "maydin@test.com", "uname": "maydin", "language": "en", "whitelist_enabled": true, "whitelist": "", "blacklist": "", "secondary_account": "maydin2@test.com", "primary_account": "", "timezone": 27, "theme": 3, "quota": 0 }
The key field to verify is: "uname": "maydin"
If the uname field is populated (not empty), the User Preference exists. Example response - non-existent user: { "objectID": "UserPreference:sgfsafhs@test.com{D:test.com}", "mdomain": "test.com", "mkey": "sgfsafhs@test.com", "uname": "", "language": "en", "whitelist_enabled": false, "whitelist": "", "blacklist": "", "secondary_account": "", "primary_account": "", "timezone": 0, "theme": 3, "quota": 0 }
If the uname field is empty like above, the user preference does not exist and must be created if needed. - How to create a user preference object:
If the user does not exist, create it using the following API call: curl -k -X POST https://<FortiMail-IP>/api/v1/UserPreference/<user@example.com> \ -b cookies.txt \ -H "Content-Type: application/json" \ -d '{ "uname": "username", "display_name": "Display Name", "is_initialize": true, "language": "en", "timezone": 27, "theme": 3 }'
Parameter explanations: - uname - Mailbox local username.
- display_name - Display name shown in webmail.
- is_initialize - Must be set to true during first-time creation.
- language - Interface language.
- timezone - Timezone identifier.
- theme - Webmail theme identifier.
- Reviewing safelist, blocklist, and secondary account fields.
Once the UserPreference object exists, the following fields can be reviewed in the GET response: { "whitelist_enabled": true, "whitelist": "", "blacklist": "", "secondary_account": "maydin2@test.com" }
Parameter explanation: - whitelist_enabled - Indicates whether safelist functionality is enabled.
- whitelist - Safelist entries.
- blacklist - Blocklist entries.
- secondary_account - Displays the configured secondary mailbox (if any).
| 
