Mailprotector Users & Groups

Mailprotector Users & Groups

Overview

Users live in user groups; user groups live under domains and are the unit of service provisioning — which products (CloudFilter, Bracket, SafeSend, XtraMail, SecureStore, hosting) a set of users gets. Manual user CRUD and directory sync are alternative population strategies for the same groups.

Key Concepts

Common Workflows

User groups and services

1. Create: POST /domains/{domain_id}/user_groups {"name": "..."}; list with mailprotector_user_groups_list.

2. Read services: GET /user_groups/{user_group_id}/services → array of {id, service_type, user_group, domain}.

3. Update services: PUT /user_groups/{user_group_id}/services with

   {"service_types": {"hosting": "other", "addons": ["bracket", "securestore"]}}
   

   One hosting value, any number of addons. Any currently active service not present in the body is deactivated — always GET the current services, merge, then PUT the full desired set.

4. Rename: PUT /user_groups/{id}; delete: DELETE /user_groups/{id} — deletes every user in the group. Move users to another group first to preserve them.

Creating users

• Single: POST /user_groups/{user_group_id}/users with {"name": "username", "password": "...", "first_name": "...", "last_name": "...", "user_type_id": 1, "aliases": ["alias1"]}. Responds 201 with an array containing the created user.
• Bulk: POST /user_groups/{user_group_id}/users/create_many with {"users": [ {...}, {...} ]} — same per-user shape.
• Each user gets <name>@<domain> plus one address per domain alias.
• Lookup: mailprotector_users_list (filterable, e.g. ?first_name=Bob), mailprotector_users_get, and mailprotector_users_find_by_address (POST /users/find_by_address {"address": "someone@domain.com"}) — searching an alias address returns the root user.

Maintaining users

• Update: PUT /users/{user_id} — first_name, last_name, phone, user_type_id.
• Reset password: POST /users/{user_id}/reset_password {"password": "..."} — sets it to the supplied value (high-impact; confirm with the operator).
• Delete: DELETE /users/{user_id} — irreversible.
• Aliases: GET /users/{user_id}/aliases; POST /users/{user_id}/aliases with the nested body {"alias": {"name": "alias-username"}} (unlike the flat aliases array on user create). The parent must be user_type "User" — mailing lists and equipment accounts cannot take aliases. An alias address is created for the domain and each domain alias.

Directory sync (AD / Entra)

1. List: GET /domains/{domain_id}/user_syncs; single: GET /user_syncs/{user_sync_id}.

2. Create (LDAP/AD only): POST /domains/{domain_id}/user_syncs with destination_user_group_id, source_type: "UserSync::LdapSource", enabled: "true", and source: {host, port, use_ssl, username, password, search_base}. New syncs are disabled by default unless enabled is passed. Google Workspace and Microsoft Graph (Entra ID / Office 365) sources must be provisioned in the web console — but once they exist, their schedule and filters are managed via the API like any other sync.

3. Schedule (per domain, not per sync): GET/PUT /domains/{domain_id}/user_sync_schedule with {"interval": 30, "enabled": true} — interval is minutes between runs; the response carries last_run_at/next_run_at.

4. Filters: GET/POST /user_syncs/{user_sync_id}/filters with {"field": "Department", "value": "Accounting", "filter_group": "all", "comparison_type_id": 1}; delete via DELETE /user_sync_filters/{id}. filter_group is all (AND) or any (OR). Comparison types:

   id	Comparison	id	Comparison
   1	Equals	5	Contains
   2	Does not equal	6	Does not contain
   3	Greater than	7	Matches
   4	Less than	8	Does not match

Gotchas

• The services PUT is declarative, not additive. Omitting an active addon deactivates it. This is the highest-risk write in this skill — read-merge-write, always.
• Sync health: alive: false on a sync means the source stopped answering; check host/credentials before touching filters.
• enabled on sync create is the string "true" in the documented body; the update accepts a boolean. Send what the endpoint shows.
• User create returns an array, even for a single user — index [0] for the created record.
• Deleting a user group deletes its users — the API will not warn.

Related Skills

• customers-and-domains — the domain must be Active before users receive mail
• quarantine-and-messages — per-user quarantine once users exist