This endpoint can be used to find messages that were either released to the recipient, with details about the user that processed the release. These logs also include messages that expired in the held queue, and were dropped by Mimecast housekeeping services.
Pre-requisites
In order to successfully use this endpoint the logged in user must be a Mimecast administrator with at least the Monitoring | Held | Read permission.
URI
To use this endpoint you send a POST request to:
/api/gateway/get-held-release-logs
Request Headers
The following request headers must be included in your request:
Field
Description
Authorization
Please see the Authorization guide for more information on building the Authorization header.
x-mc-req-id
A randomly generated GUID, for example,
8578FCFC-A305-4D9A-99CB-F4D5ECEFE297
x-mc-app-id
The Application ID provided with your Registered API Application.
x-mc-date
The current date and time in the following format, for example,
An object defining paging options for the request.
Paginiation Object
Field
Type
Required
Description
pageSize
Number
Optional
The number of results to request.
pageToken
String
Optional
The value of the 'next' or 'previous' fields from an earlier request.
Data
Field
Type
Required
Description
searchBy
Search Object
Optional
Field name and value on which to base search.
filterBy
Array of Filter Objects
Optional
Filters that should be applied to the search results.
start
Date String
Optional
The start date of results to return in ISO 8601 format. Default value is one month before the current date.
end
Date String
Optional
The end date of results to return in ISO 8601 format. Default value is the current date.
Search Object
Field
Type
Required
Description
fieldName
String
Optional
The field on which to be filtered. Possible field names are: all, operator, from, to, subject, info or heldReason
value
String
Optional
The value of which the filter will be applied.
Filter Object
Field
Type
Required
Description
fieldName
String
Optional
The field on which to be filtered. Possible values are: route, status or attachments.
value
String
Optional
The value of which the filter will be applied. Possible values for route are: all, internal, outbound, inbound or external. Possible values for status are: released or rejected. Possible values for attachments are: true or false.
A pageToken value that can be used to request the next page of results. Only returned if there are more results to return.
previous
String
A pageToken value that can be used to request the previous page of results. Only returned if there is a previous page.
data
Field
Type
Description
heldReleaseLogs
Array of released Objects
The resulting messages that match the search and filter queries.
Released Object
Field
Type
Description
spamProcessingDetail
Spam Processing Detail Object
Object containing the spam, sender validation and managed sender scan results.
attachments
Boolean
Indicates whether the message contains attachments.
messageInfo
String
Additional information around the release reason.
subject
String
The released message's subject line.
detectionLevel
String
Spam detection level, if held by a spam policy. Possible values are: relaxed, moderate, aggressive, cluster or whitelisted_cluster
heldGroup
String
The recipient group of the held message, if message was sent to a group.
operator
String
Email address of the user that released the message.
fromEnv
Email Address Object
Envelope from address information
rejectReason
String
Detail on the reason a message was rejected, if message was rejected.
route
String
Message direction. Possible values are: inbound or outbound.
size
Number
Total size of the message, in bytes.
heldReason
String
Detail around the reason the message was initially held. If held by a specific policy definition, this will be the name of the policy definition that triggered the message to be held.
spamScore
Number
The message spam score, based on the applied spam scanning policy definition.
id
String
The Mimecast secure ID of the specific message release log.
to
Array of Email Address Objects
Envelope from address information
released
Date String
Timestamp of the message release action in ISO 8601 format.
fromHdr
Email Address Object
Header from address information
status
String
Status of the message. Possible values are released or rejected.
policy
String
Name of the policy definition that triggered the message to be held.
Spam Processing Detail Object
Field
Type
Description
greyEmail
Boolean
Indicates with the spam was classified as graymail or bulk. Note that this API uses graymail and greymail interchangeably.
permittedSender
Information Object
Indicates if the sender has been permitted by policy.
managedSender
Information Object
Indicates if the sender has been permitted by a Managed Sender entry.
dkim
Information Object
Indicates if the message passed DKIM checks.
spf
Information Object
Indicates if the message passed SPF checks.
rbl
Information Object
Indicates if the message passed RBL checks.
dmarc
Information Object
Indicates if the message passed DMARC checks.
spamVerdict
Spam Verdict Object
Information about the spam scanning results.
Email Address Object
Field
Type
Description
emailAddress
String
The routable email address of the user
displayableName
String
Display name of the user address. If none exists, this field will be empty.
Spam Verdict Object
Field
Type
Description
decision
String
Indicating what the ultimate verdict was for the message.
description
String
Description of the spam verdict decision.
risk
String
Identified risk level within the spam detection. Possible values are: negligible, low, high.
categories
Array of Category Objects
Spam detection type categories
Spam Category Object
Field
Type
Description
name
String
Name of the scanning category. Possible values are spam, phishing or graymail. Note that this API uses graymail and greymail interchangeably.
risk
String
Identified risk level within the category detection. Possible values are: negligible, low, high.
subcategories
Array of Spam Subcategory Objects
Additional category information under the high-level category.
Spam Subcategory Object
Field
Type
Description
name
String
Name of the scanning subcategory.
risk
String
Identified risk level within the subcategory detection. Possible values are: negligible, low, high.
augmentations
Array of Augmentation Objects
Component of the message where this subcategory was identified.
Augmentation Object
Field
Type
Description
name
String
Name of the message component.
risk
String
Identified risk level within the component scanning. Possible values are: negligible, low, high.
Information Object
Field
Type
Description
allow
Boolean
Indicates if this check was performed.
info
String
Details about the check result.
Sample Code
Sample code is provided to demonstrate how to use the API and is not representative of a production application. To use the sample code; complete the required variables as described, populate the desired values in the request body, and execute in your favorite IDE. Please see the Global Base URL's page to find the correct base URL to use for your account.