Mimecast

AirMDR connects to Mimecast through a Mimecast API 2.0 application, authenticating with a Client ID and Client Secret.

Mimecast API 2.0 authorises every call through two independent gates, and both must be opened or the skills return HTTP 403:

API Products — the categories of endpoints the application is allowed to reach. Anything outside the assigned products is refused with app_forbidden, no matter how permissive the role is.
Application Role — the administrative permissions the keys may exercise once the product is assigned. A missing permission is refused with sub-code 0002.

Assigning a role alone is the most common setup mistake. Credentials that authenticate successfully against /oauth/token tell you nothing about either gate.

Pre-requisites

The administrator performing this setup needs a role with Read and Edit on API Application Permissions under the Service menu, and a Security Permissions setting of Manage Application Roles.

Authentication and Access

AirMDR authenticates with Mimecast using a Client ID and Client Secret generated for a Mimecast API 2.0 application.The application requires both of the following:

Configuration	Purpose
API Products	Determines which categories of API endpoints the application can access.
Application Role	Determines which operations the application can perform within the selected API Products.

Successful authentication confirms that the credentials are valid. It does not confirm that the application has the products and permissions required to run a skill.

Configure Access for Investigation Skills

Required API ProductsSelect the products required by the skills you intend to use. The following six products cover the investigation skills listed below.

API Product	Skills
Audit Events	`get_held_release_logs`
Security Events	`get_ttp_url_protection_logs`, `get_ttp_attachment_logs`, `get_ttp_impersonation_logs`
Email Security Cloud Gateway	`message_finder_search`, `get_message_info`
Data Retention	`search_mimecast_message_archive`, `get_message_content`
Threat Management	`get_remediation_incident`
User and Group Management	`find_groups`

Policy Management is required only when using the corresponding policy-management skills.

Permissions and Roles by Skill

Create a dedicated application role with the permissions required for your selected skills.

Skill	Purpose	Required role permission
`get_held_release_logs`	Retrieve held-message release logs.	Monitoring → Held → Read
`get_ttp_url_protection_logs`	Retrieve URL Protection event logs.	Monitoring → URL Protection → Read
`get_ttp_attachment_logs`	Retrieve Attachment Protection event logs.	Monitoring → Attachment Protection → Read
`get_ttp_impersonation_logs`	Retrieve Impersonation Protection event logs.	Monitoring → Impersonation Protection → Read
`message_finder_search`	Search message tracking information.	Gateway → Tracking → Read
`get_message_info`	Retrieve message information.	Gateway → Tracking → Read
`search_mimecast_message_archive`	Search archived email messages.	Archive → Search → Read
`get_message_content`	Retrieve email message content.	Archive → Read and Archive → Search Content View
`get_remediation_incident`	Retrieve threat remediation incident information.	Services → Threat Remediation → Read
`find_groups`	Find groups in Mimecast.	Directories → Groups → Edit

Message content permissions: Archive → Read and Archive → Search Content View are protected permissions. A Super Administrator must grant these permissions to the custom application role.

Group lookup permissions: Although find_groups retrieves information, Mimecast requires Directories → Groups → Edit for this operation.

Setup Steps

Create an Application Role for AirMDR

Sign in to the Mimecast Administration Console.
Navigate to Account → Admin Roles.
Create a dedicated role for the integration, such as AirMDR Integration.

Grant the permissions listed in Permissions and Roles by Skill for the skills you intend to use.

List of Permissions (For reference)

Permission	Enables
`Monitoring \| Held \| Read`	Held and released message logs
`Monitoring \| Held \| Edit`	Releasing held messages
`Monitoring \| URL Protection \| Read`	URL Protect event logs
`Monitoring \| Attachment Protection \| Read`	Attachment Protect event logs
`Monitoring \| Impersonation Protection \| Read`	Impersonation Protect event logs
`Gateway \| Tracking \| Read`	Message tracking and message info
`Gateway \| Managed Senders \| Edit`	Permitting or blocking a sender
`Gateway \| Policies \| Edit`	Creating blocked sender policies
`Archive \| Search \| Read`	Archive search
`Archive \| Read`	Retrieving a message body
`Archive \| Search Content View`	Retrieving message detail and headers
`Services \| Threat Remediation \| Read`	Reading remediation incidents
`Services \| Threat Remediation \| Edit`	Creating remediation incidents
`Services \| Targeted Threat Protection - URL Protect \| Edit`	Creating managed URLs
`Directories \| Groups \| Edit`	Finding groups and adding group members

Archive | Read and Archive | Search Content View are protected permissions. The Basic Administrator role has no access to protected permissions and can read an email body only while that email is still held, so message content retrieval fails under it even when everything else is configured correctly. Only a Super Administrator can grant protected permissions to a custom role. If message body retrieval is in scope, have a Super Administrator add them, or assign Full Administrator.

Directories | Groups | Edit is required even to read groups — Mimecast does not expose a read-only permission for find-groups.

Save the role.

Create an API 2.0 Application

Navigate to Integrations → Integrations Hub.
Review and accept the API Terms and Conditions if prompted.
Locate the Mimecast API 2.0 tile and click Configure New.

Complete the application details:

Field	Value
Application Name	Enter a unique name, such as AirMDR.
Products	Select the products required by your selected skills.
Application Role	Select the role created in Step 1.
Description	Enter a description, such as API integration for AirMDR email security investigations.

Under Notification Settings, enter the technical contact’s name or team and email address.
Click Save.
Copy the generated Client ID and Client Secret to an approved secrets vault before closing the credentials window.
Copy both to a secure location before closing. The Client Secret is shown only once and cannot be retrieved later — if it is lost, use Reset Keys on the application, which invalidates the previous pair immediately.
Click Close.
Editing an existing application. Since June 2026 the Role and Products fields can be modified in place — an application missing products no longer has to be deleted and recreated, and credentials do not need regenerating. Go to Integrations → Integrations Hub, click View on the API 2.0 tile, select the application, open the options menu and click Edit.Applications created before the Integrations Hub migration are still managed under Integrations → API and Platform Integrations on the API 2.0 Applications tab.

Send the Client ID and Client Secret to AirMDR securely, or configure Mimecast yourself in the AirMDR Integrations Dashboard.

Review an Existing Application

Navigate to Integrations → Integrations Hub.
Locate the Mimecast API 2.0 tile and click View.
Select the application used by AirMDR.
Open the application options menu and select Edit.
Review the assigned Products and Application Role against the requirements above.
Update the available settings and click Save.

Legacy applications: Applications created before the Integrations Hub migration may remain under Integrations → API and Platform Integrations → API 2.0 Applications.If the required product selection cannot be changed, consult Mimecast support for the supported procedure for your tenant.

Validate Authentication and Access

Sample Request & Response

Run the following command with the application credentials:

curl --request POST \
  'https://api.services.mimecast.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET'

A successful response returns an access token. Treat the token and application credentials as secrets.

A successful token response confirms only that the keys are valid. It does not verify the products or the role, both of which are enforced per endpoint. To confirm the products, call an endpoint from each product with the returned bearer token.

Configure Mimecast in AirMDR Integrations Dashboard

Navigate to AirMDR, provide the credentials and click Login.
Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select Integrations.
Use the search option, enter the keyword “Mimecast”, select the Connections tab, and click the + New Connection button.

Use the following values in the AirMDR integration configuration screen:

Field	Value to enter
Instance	A unique name for the connection, such as `Example-Mimecast`.
Organization	The AirMDR organization that owns the connection.
Description	A brief description, such as `Mimecast email security investigation and response`.
Client ID	The Client ID generated for the Mimecast API 2.0 application configured for AirMDR.
Client Secret	The corresponding Client Secret copied when the application credentials were generated. The secret cannot be retrieved later; if lost, regenerate the application credentials and update the connection.

Expand Advanced Configuration if required. (Optional)

In Remote Agent, select an AirMDR Remote Agent when Mimecast API requests must run through an approved network route. Ensure the selected agent can resolve and reach api.services.mimecast.com over HTTPS on TCP port 443. For direct connectivity from AirMDR, leave this field unselected.
In Expiry, select a date according to your organization’s credential-rotation policy. If an expiration date applies to the Mimecast application credentials, select that date or an earlier date.

Expiry controls credential validity in AirMDR. It does not automatically rotate, extend, or revoke the Client ID and Client Secret in Mimecast. This setting is separate from the lifetime of the OAuth access tokens obtained using those credentials.

Before expiry, regenerate the application credentials in Mimecast and promptly update the Client ID, Client Secret, and Expiry in AirMDR. Save and validate the connection. Resetting the Mimecast application keys invalidates the previous credentials, so coordinate the update to minimize disruption.

Enter the generated Client ID and Client Secret in the Authentication Details field params, and click Save.

Skills provided by this Integration and required Permissions

Investigation and Information Retrieval Skills

These skills retrieve information without modifying messages, policies, or group membership.

Skill	Purpose	Access type	Required permission
Search Mimecast Messages	Search message tracking information using filters such as time range, route, and status to investigate email delivery and traffic.	Read	API Product: Email Security Cloud Gateway. Role permission:Gateway → Tracking → Read.
Get Mimecast Message Info	Retrieve message details using its unique Mimecast ID, including sender, recipient, subject, timestamps, and spam score.	Read	API Product: Email Security Cloud Gateway. Role permission:Gateway → Tracking → Read.
Get Mimecast Held Release Logs	Retrieve logs of messages released from the hold queue to support monitoring and auditing.	Read	API Product: Audit Events. Role permission: Monitoring → Held → Read.
Get Mimecast TTP Attachment Logs	Retrieve attachment protection logs filtered by time range, scan results, and message routing to investigate attachment threats.	Read	API Product: Security Events. Role permission: Monitoring → Attachment Protection → Read.
Get Mimecast TTP Impersonation Logs	Retrieve impersonation protection logs using filters such as time range, identifiers, actions, and malicious tagging status.	Read	API Product: Security Events. Role permission: Monitoring → Impersonation Protection → Read.
Get TTP URL Protection Logs	Retrieve URL protection logs using filters such as scan results and message routing to investigate suspicious links.	Read	API Product: Security Events. Role permission: Monitoring → URL Protection → Read.
Search mimecast message archive	Search archived messages using criteria such as time range, sender, recipient, subject, and message body.	Read	API Product: Data Retention. Role permission: Archive → Search → Read.
Get Mimecast Message Content	Retrieve archived message metadata, headers, authentication results, attachment names and hashes, and message body; the body is truncated at 100,000 characters.	Read	API Product: Data Retention. Role permissions: Archive → Read and Archive → Search Content View.
Get Mimecast Remediation Incidents	Retrieve an incident by ID or search for incidents to review remediation results and identify existing incidents before creating duplicates.	Read	API Product: Threat Management. Role permission:Services → Threat Remediation → Read.
Find Mimecast Groups	Find profile groups and retrieve group IDs required for membership updates or identifying groups referenced by sender policies.	Read operation; requires Edit permission	API Product: User and Group Management. Role permission:Directories → Groups → Edit.

Permission considerations

Get Mimecast Message Content requires protected Archive permissions. A Super Administrator must grant these permissions to the custom application role.
Find Mimecast Groups performs a lookup, but Mimecast requires Directories → Groups → Edit for this operation.

Response, Remediation, and Management Skills

These skills modify message handling, sender controls, URL controls, remediation incidents, or group membership. Grant the corresponding permissions only when these capabilities are required.

Skill	Purpose	Access type	Required permission
Release Mimecast Held Messages	Release up to 25 held messages per call for delivery to their recipients; each message is processed independently.	Write — release messages	API Product: Email Security Cloud Gateway. Role permission:Monitoring → Held → Edit.
Permit or Block Mimecast Sender	Permit or block a specific external sender for an individual internal recipient using a Managed Sender entry; requires a complete sender email address.	Write — manage sender entries	API Product: Email Security Cloud Gateway. Role permission:Gateway → Managed Senders → Edit.
Create Mimecast Blocked Sender Policy	Create a policy to reject messages from a sender address or domain; defaults to a tenant-wide, non-expiring block, with optional recipient and time restrictions.	Write — create policies	API Product: Policy Management. Role permission:Gateway → Policies → Edit.
Create Mimecast Managed URL	Create an entry to permit or block a URL or domain; explicit URL matching requires the HTTP or HTTPS scheme, while domain matching accepts a bare domain.	Write — manage URL controls	API Product: Policy Management. Role permission:Services → Targeted Threat Protection - URL Protect → Edit.
Create Mimecast Remediation Incident	Create an asynchronous incident to search for and purge malicious emails across tenant mailboxes using exactly one criterion: message ID, attachment hash, or a URL in the message body.	Write — initiate remediation	API Product: Threat Management. Role permission:Services → Threat Remediation → Edit.
Add Mimecast Group Member	Add up to 500 email addresses or domains to a profile group per call, using a group ID retrieved through Find Mimecast Groups.	Write — update group membership	API Product: User and Group Management. Role permission:Directories → Groups → Edit.

Operational considerations

Use Permit or Block Mimecast Sender for an individual sender and recipient pair. Use Create Mimecast Blocked Sender Policy for sender-address or domain blocking across a broader scope.
Adding members to a group affects sender blocking only when an applicable blocked sender policy already references that group.
Remediation runs asynchronously. Use Get Mimecast Remediation Incidents to check progress and confirm the outcome.

Additional Information

🧰 Error Handling

Review both the HTTP status and the response body when a Mimecast skill fails. An HTTP 200 response can contain an operation-level failure.

Error or symptom	Possible cause	Recommended action
`400 — Bad Request`	Invalid inputs or an incorrectly formatted request.	Verify the required fields, identifiers, dates, and filters. Correct the inputs before retrying.
`401 — Unauthorized`	Invalid application credentials or an invalid or expired access token.	Verify the Client ID and Client Secret configured in AirMDR. For direct API testing, obtain a new access token if the previous token has expired.
`403` with `app_forbidden`	The application does not have the API Product required by the endpoint.	Review the application’s assigned Products in Mimecast and confirm that the required product is included.
`403` with sub-code `0002`	The Application Role lacks a required permission.	Check the skill’s required role permissions and update the assigned role.
`404 — Not Found`	The endpoint or requested resource cannot be found.	Verify the endpoint and resource identifier. Confirm that the resource exists and is accessible.
`429 — Quota Exceeded`	Requests exceeded the endpoint’s rate limit.	Pause requests for the reset period indicated by Mimecast, then retry. Reduce polling frequency or concurrent requests if failures persist.
`500`, `502`, `503`, or `504`	A Mimecast service or upstream request failed.	Retry after a delay. For response actions, check whether the original operation completed before submitting it again.
Message content retrieval fails.	Protected Archive permissions are missing.	Verify Archive → Read and Archive → Search Content View. A Super Administrator must grant these protected permissions to the custom role.
Group lookup fails.	The required group permission is missing.	Verify Directories → Groups → Edit, including when running Find Mimecast Groups.
A batch operation reports mixed results.	Some items succeeded while others failed.	Review each item’s result and retry only failed items after correcting the cause.

Important: Before retrying a remediation or policy-creation action, check its existing result to avoid duplicate operations.

🔄 Monitoring & Logs

Review skill execution results and the associated playbook run in AirMDR to monitor integration activity.

Monitoring area	Information to review
Authentication and authorization	Authentication failures, missing API Products, and insufficient Application Role permissions.
Skill execution	Skill name, execution time, inputs, completion status, returned records, and error details available in the execution result.
Email investigations	Message tracking results, held-release logs, and URL, attachment, and impersonation protection logs.
Response actions	Results for message release, sender controls, URL controls, policy creation, and group membership updates.
Remediation progress	Use Get Mimecast Remediation Incidents to check the outcome of an incident created through Create Mimecast Remediation Incident.
Request volume	Repeated rate-limit responses, overlapping searches, and unnecessary concurrent requests.

When investigating a failure, record:

AirMDR connection name and affected skill.
Execution or playbook run identifier, where available.
Timestamp and time zone.
HTTP status, error code, and sanitized error message.
Mimecast request ID, where returned.

Exclude Client Secrets, access tokens, and unnecessary message content from diagnostic records.

🛑 Security & Access Best Practices

✅ Do

Use a dedicated Mimecast API 2.0 application and custom Application Role for AirMDR.
Assign only the API Products and role permissions required by the selected skills.
Grant response permissions only when the corresponding response capabilities are required.
Store application credentials in an approved secrets vault.
Restrict access to the AirMDR connection and playbooks that release messages, purge emails, or change security controls.
Review recipient scope, sender addresses, domains, URLs, and policy duration before executing response actions.
Validate the required skills after changing credentials, products, or permissions.
Review application access periodically and remove unused permissions.

❌ Don’t

Share Client Secrets or access tokens through email, chat, screenshots, or support tickets.
Assign broad administrator access solely to bypass a permission error.
Assume that successful authentication confirms access to every skill.
Release held messages or permit senders and URLs without reviewing the associated security findings.
Create a tenant-wide blocked sender policy when a narrower recipient scope meets the requirement.
Repeat remediation or policy-creation requests without checking the previous execution result.
Disable certificate validation to work around connectivity errors.

👉 Support & Maintenance

📧 Contact AirMDR Support through your designated support channel.
🔁 Rotate credentials regularly. Recommended cadence: As per your internal security policy

🔄 Routine Maintenance

Activity	Recommended action
Credential rotation	Rotate credentials according to your organization’s policy. Coordinate the Mimecast key reset with the AirMDR connection update because resetting keys invalidates the previous credentials.
Connection validation	Validate authentication and run the required skills after configuration changes.
Permission review	Confirm that assigned Products and Application Role permissions match the capabilities currently in use.
Playbook maintenance	Review skill inputs, dependencies, and response-action scope when updating playbooks.
API changes	Review Mimecast API announcements and AirMDR release notes for changes affecting authentication, endpoints, or supported skills.
Decommissioning	Disable dependent playbooks, remove the AirMDR connection, and disable or delete the dedicated Mimecast application when it is no longer required.

🛑 Data Flow & Security

Authentication Flow

AirMDR uses the configured Client ID and Client Secret to request an OAuth access token from https://api.services.mimecast.com/oauth/token.
Mimecast validates the application credentials and returns an access token.
AirMDR presents the bearer token when calling Mimecast API endpoints.
Mimecast evaluates the application’s assigned API Products and Application Role permissions before allowing the operation.

Data Exchanged

Data category	Information exchanged
Message investigation data	Message identifiers, sender and recipient addresses, subjects, timestamps, routing information, and message status.
Security event data	URL protection, attachment protection, impersonation protection, and held-message release information.
Archived message data	Search results, message metadata, headers, authentication results, attachment names and hashes, and message body content requested by the selected skill.
Remediation data	Search criteria, incident identifiers, remediation status, and message-processing results.
Configuration changes	Sender controls, blocked sender policies, managed URL entries, and profile group membership changes submitted through response skills.

Transport and Data Handling

Communication with the Mimecast API uses HTTPS over TCP port 443.
The API hostname used by this integration is api.services.mimecast.com.
Retrieved message content and security events may contain personal, confidential, or security-sensitive information. Restrict access to execution results and associated case data.
Apply your organization’s approved retention and access policies to data retained in cases, playbook results, and exported diagnostic records.
Review the applicable AirMDR and Mimecast security documentation for platform-specific encryption-at-rest and retention details.

Getting Started

AirMDR Detections

Integrations

API Reference

AirMDR Product Suite

Pre-requisites

Setup Steps

Validate Authentication and Access

Configure Mimecast in AirMDR Integrations Dashboard

Skills provided by this Integration and required Permissions

Additional Information

​Pre-requisites

​Setup Steps

​Validate Authentication and Access

​Configure Mimecast in AirMDR Integrations Dashboard

​Skills provided by this Integration and required Permissions

​Additional Information

Pre-requisites

Setup Steps

Validate Authentication and Access

Configure Mimecast in AirMDR Integrations Dashboard

Skills provided by this Integration and required Permissions

Additional Information