Mimecast User Management API Guide

Auth method: OAuth 2.0 (client credentials or authorization code flow)

Setup steps

1. Log in to the Mimecast Administration Console.
2. Navigate to Administration > Services > API and Platform Integrations.
3. Create a new API application; record the Client ID and Client Secret.
4. Select the required permission scopes for the application.
5. POST to https://api.services.mimecast.com/oauth/token with grant_type=client_credentials, client_id, and client_secret to obtain a Bearer access token.
6. Include the token in all API requests as Authorization: Bearer .

Required scopes

List Users

• Method: GET
• URL: https://api.services.mimecast.com/api/user/get-internal-users
• Watch out for: Endpoint returns internal (managed) users only; external/guest users require a separate call.

Request example

GET /api/user/get-internal-users?pageSize=100 HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Response example

{
  "data": [{"id":"abc123","emailAddress":"user@example.com","name":"Jane Doe"}],
  "meta": {"pagination":{"pageToken":"tok_xyz","totalCount":250}}
}

Get User

• Method: POST
• URL: https://api.services.mimecast.com/api/user/get-internal-users
• Watch out for: Mimecast v1 API uses POST for lookups; v2 REST API uses GET with query params. Confirm which API version your app registration targets.

Request example

POST /api/user/get-internal-users HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{"data":[{"emailAddress":"user@example.com"}]}

Response example

{
  "data": [{"id":"abc123","emailAddress":"user@example.com","name":"Jane Doe","status":"active"}]
}

Create User

• Method: POST
• URL: https://api.services.mimecast.com/api/user/create-managed-sender
• Watch out for: User creation via native API is limited; full lifecycle provisioning is recommended via SCIM 2.0 for IdP-driven workflows.

Request example

POST /api/user/create-managed-sender HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{"data":[{"emailAddress":"newuser@example.com","name":"New User"}]}

Response example

{
  "data": [{"id":"def456","emailAddress":"newuser@example.com","status":"active"}]
}

Update User

• Method: POST
• URL: https://api.services.mimecast.com/api/user/update-managed-sender
• Watch out for: Only fields included in the request body are updated; omitted fields retain existing values.

Request example

POST /api/user/update-managed-sender HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{"data":[{"id":"def456","name":"Updated Name"}]}

Response example

{
  "data": [{"id":"def456","emailAddress":"newuser@example.com","name":"Updated Name"}]
}

Delete User

• Method: POST
• URL: https://api.services.mimecast.com/api/user/delete-managed-sender
• Watch out for: Deletion is irreversible. Mimecast may retain email archive data per retention policy even after user deletion.

Request example

POST /api/user/delete-managed-sender HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{"data":[{"id":"def456"}]}

Response example

{
  "data": [{"id":"def456","status":"deleted"}]
}

List Groups

• Method: POST
• URL: https://api.services.mimecast.com/api/directory/find-groups
• Watch out for: Groups can be cloud-managed or LDAP-synced; only cloud groups are writable via API.

Request example

POST /api/directory/find-groups HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{"data":[{"source":"cloud"}]}

Response example

{
  "data": [{"id":"grp001","description":"All Staff","source":"cloud"}]
}

Add User to Group

• Method: POST
• URL: https://api.services.mimecast.com/api/directory/add-group-member
• Watch out for: Adding a user to an LDAP-synced group via API will fail; only cloud-managed groups accept API membership changes.

Request example

POST /api/directory/add-group-member HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{"data":[{"id":"grp001","emailAddress":"user@example.com"}]}

Response example

{
  "data": [{"id":"grp001","emailAddress":"user@example.com","status":"added"}]
}

Get Account Info

• Method: POST
• URL: https://api.services.mimecast.com/api/account/get-account
• Watch out for: Returns the account associated with the authenticating API application; multi-tenant MSP setups require separate credentials per account.

Request example

POST /api/account/get-account HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{"data":[{}]}

Response example

{
  "data": [{"accountCode":"ACCT001","companyName":"Example Corp","maxUsers":500}]
}

• Rate limits: Mimecast enforces per-application rate limits. Exact numeric limits are not publicly documented; limits vary by plan and endpoint category.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: When rate limited, the API returns HTTP 429. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers. Mimecast recommends exponential back-off.
• Pagination method: token
• Default page size: 100
• Max page size: 500
• Pagination pointer: pageToken

• Webhooks available: No
• Webhook notes: Mimecast does not offer a general-purpose outbound webhook system for user lifecycle events. Event-driven integrations rely on polling the API or using SIEM/log streaming integrations.
• Alternative event strategy: Use Mimecast's SIEM integration or scheduled API polling to detect user changes. Some IdP-driven flows (Okta, Entra ID) push changes via SCIM rather than webhooks.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://api.services.mimecast.com/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, POST /Groups, PATCH /Groups/{id}, DELETE /Groups/{id}

Limitations:

• Requires Enterprise plan; not available on lower tiers.
• SSO must be configured and active before SCIM provisioning can be enabled.
• Supported IdPs include Okta, Microsoft Entra ID (Azure AD), and OneLogin; Google Workspace is not officially supported.
• SCIM provisioning manages cloud-directory users only; LDAP-synced users are not writable via SCIM.
• Group push support varies by IdP connector; verify group writeback capability in the IdP SCIM app configuration.
• Deprovisioning via SCIM disables the user account but may not immediately remove email archive access.

The three primary automation scenarios against the Mimecast API each carry distinct constraints that affect integration design. For IdP-driven provisioning, SCIM 2.

0 at https://api.services.mimecast.com/scim/v2 is the correct path - it supports the full Users and Groups lifecycle (GET, POST, PUT, PATCH, DELETE) - but requires Enterprise tier and fully active SSO before the first SCIM push; provisioning fails if SSO is not live.

Supported IdPs are Okta, Microsoft Entra ID, and OneLogin; Google Workspace is not officially supported. For direct REST provisioning, user creation via the native API (POST /api/user/create-managed-sender) is limited in scope; Mimecast's own documentation recommends SCIM for full lifecycle workflows.

Group membership writes via POST /api/directory/add-group-member only succeed against cloud-managed groups - LDAP-synced groups are read-only via API, and the group source field must be checked before attempting any write.

For deprovisioning, SCIM PATCH active=false and SCIM DELETE both result in account disable rather than guaranteed hard deletion; behavior varies by IdP configuration and should be validated in a non-production environment.

Email archive data is retained per the account's retention policy regardless of how deletion is triggered. Bulk operations are not supported; every user create or update is one record per API call.

Provision a new employee via SCIM from Okta

1. Ensure Mimecast Enterprise plan is active and SSO is configured with Okta as the IdP.
2. In Okta Admin Console, add the Mimecast SCIM application from the Okta Integration Network.
3. Configure the SCIM base URL (https://api.services.mimecast.com/scim/v2) and authenticate using an OAuth 2.0 Bearer token generated from a Mimecast API application.
4. Assign the new employee's Okta profile to the Mimecast SCIM app.
5. Okta pushes a POST /Users request to Mimecast SCIM; Mimecast creates the cloud-directory user.
6. Verify user appears in Mimecast Administration Console under Directories > Internal Directories.

Watch out for: If SSO is not active, SCIM provisioning will fail silently or return 401. Always validate SSO login before enabling SCIM push.

Deprovision a user when they leave the organization

1. Trigger deprovisioning from the IdP (Okta/Entra ID) by removing the user's app assignment or deactivating their account.
2. IdP sends a PATCH /Users/{id} with active=false (or DELETE /Users/{id}) to the Mimecast SCIM endpoint.
3. Mimecast disables the user account, blocking email delivery and console access.
4. Confirm the user status is 'disabled' via GET /Users/{id} or in the Mimecast Admin Console.
5. Email archive data is retained per the account's configured retention policy.

Watch out for: SCIM DELETE vs. PATCH active=false behavior depends on IdP configuration. Mimecast may treat both as a disable rather than a hard delete; verify behavior in a test environment.

Add a user to a policy group via REST API

1. Authenticate and obtain an OAuth 2.0 Bearer token via POST to /oauth/token.
2. Call POST /api/directory/find-groups with source=cloud to retrieve the target group ID.
3. Call POST /api/directory/add-group-member with the group ID and the user's emailAddress.
4. Verify membership by calling POST /api/directory/get-group-members with the group ID.
5. Apply or confirm any Mimecast policies (e.g., content examination, URL protection) that are scoped to this group.

Watch out for: Only cloud-managed groups are writable via API. Attempting to add members to LDAP-synced groups returns an error. Check the group source field before attempting writes.

Integrating Mimecast into an identity graph without accounting for its dual-API architecture introduces silent correctness failures. A pipeline built against v1 HMAC-SHA1 endpoints will break if the app registration is later migrated to v2 OAuth 2.0, and the error surface - auth failures rather than version errors - makes the root cause non-obvious.

The List Users endpoint returns internal managed users only; external and guest users require a separate call, meaning a naive full-sync will produce an incomplete identity graph with no error signal.

SCIM provisioning manages cloud-directory users exclusively - LDAP-synced users are not writable via SCIM - so any identity graph that assumes SCIM write coverage is complete will silently miss a subset of the user population.

Webhooks are not available for user lifecycle events; event-driven architectures must fall back to scheduled polling or SIEM log streaming, which introduces latency between real-world access changes and graph state.

Because SCIM requires SSO to be active as a prerequisite, any SSO configuration change or outage can silently break provisioning without surfacing an explicit SCIM error.