MailFilterList report

Article
07/28/2015

The MailFilterList REST URI provides the string values allowed in other Office 365 reports. Items are grouped by SelectTarget values. Values in each group are intended to be used in $filter query options.

Applies to: Office 365

In this article
REST URI
Fields
Remarks
Examples
Input parameters and report output columns
Compatibility
Corresponding PowerShell cmdlets
Permissions
Data granularity, persistence, and availability

REST URI

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailFilterList[?ODATA options]

Fields

The following fields can be specified in $select, $filter and $orderby ODATA2 query options. All fields are returned if no $select option is provided.

Name	WCF Type*	EDM Type*	[In/Out]** Description	Example values	Added in service version
Display	string	None specified	[In/Out] A version of the Value field that can used to display the selection for use in other reports.	RedirectMessage or RemoveMessageHeader	2013-V1
Domain	string	None specified	[In/Out] a fully-qualified domain name (FQDN).	example.onmicrosoft.com	2013-V1
Organization	string	None specified	[In/Out] Office 365 organization identifier, in the form of an FQDN.	example.onmicrosoft.com	2013-V1
ParentTarget	string	None specified	[In/Out] The type of item this entry belongs to. Combined with the ParentValue field, this creates a category/sub-category relationship in the entries. The value of this field matches a SelectionTarget value to specify the type of parent. As of February 2013, DlpPolicy is the only value that will appear.	DlpPolicy	2013-V1
ParentValue	string	None specified	[In/Out] The name of the parent category, of which this entry is a sub-category.	OrgDlpPolicyName	2013-V1
SelectionTarget	string	None specified	[In/Out] The category that contains the entry. The value of the SelectionTarget corresponds to field name in other reports.	Actions, EventTypes	2013-V1
Value	string	None specified	[In/Out] The value of the entry, to be used as the comparison string for other reports.	example.onmicrosoft.com	2013-V1

*WCF Type refers to the .NET Framework data type assigned to the field when you create a Windows Communications Framework (WCF) Service Reference in Visual Studio. The EDM Type refers to the ADO.NET Entity Data Model (EDM) types returned in Atom-formatted reports.

**[In/Out]: see the Input parameters and report output columns section.

Remarks

Each entry in the report includes several fields of metadata. For more information, see Common metadata returned by the Office 365 Reporting web service.

If you are building a user interface based on the values returned by this report, use the Display field in the user interface, and use the Value field in $filter query options for those reports. Your application should not assume that Display and Value will always be the same.

SelectionTarget categories

The MailFilterList report provides strings for use in creating $filter query options for other reports. For those reports, you can specify which entries the system will return by specifying values to be matched to report fields. For example, in a MailDetailMailware report, you can specify that the report return only entries where the message was sent to the quarantine mailbox, by using $filter=Action eq ‘Quarantine’. The Quarantine value should be selected from the list of possible ActionsValues returned by MailFilterList, to ensure matches occur correctly. The table below lists the categories defined by SelectionTarget values and their corresponding fields in the other reports. The list of values associated with each SelectionTarget category can vary by domain, subscription, and configuration. For example, the DlpPolicy values returned will include policies created by the administrator.

SelectionTarget	Corresponding field names, report names, and meaning
Actions	Action field in the MailDetailDlpPolicy, MailDetailMalware, MailDetailSpam, MailDetailTransportRule, MailTrafficPolicy, MailTraffic, and MessageTraceDetail reports. Specifies what action was performed on the message as the system processed it. This list may be extended via configuration changes by an administrator.
DlpPolicy	DlpPolicy field in the MailDetailDlpPolicy, and MailTrafficPolicy reports. A data loss prevention (DLP) policy contains one or more DLP rules.
DlpRule	TransportRule field in the MailDetailDlpPolicy, MailTrafficPolicy, and MailTrafficSummary reports. Each DlpRule entry will have a ParentTarget field value of DlpPolicy, and its ParentValue field will be set to the name of an entry in the DlpPolicy category.
Domain	Domain field in the MailDetailDlpPolicy, MailDetailMalware, DailDetailSpam, MailDetailTransportRule, MailTrafficPolicy, MailTraffic, MailTrafficSummary, and MailTrafficTop reports. These entries specify the FQDNs assigned to the organization.
EventTypes	EventType field in the MailDetailDlpPolicy, MailDetailMalware, MailDetailSpam, MailDetailTransportRule, MailTrafficPolicy, MailTraffic, MailTrafficTop reports. Also the Event field in the MessageTraceDetail report. These entries specify what action was performed during the processing of the message.
TransportRule	TransportRule field in the MailDetailDlpPolicy, MailDetailTransportRule, MailTrafficPolicy, and MailTrafficSummary reports.

The following sections provide details about MailFilterList report entries with the indicated SelectionTarget values.

SelectionTarget eq ’Actions’ values

MailFilterList entries that have $filter=SelectionTarget eq ’Actions’ indicate what automatic or administrative action was taken on the spam message. If no action has been performed, the field will be null. The following table lists the other available actions. Remember that these actions often require some administrative configuration. For example, when a spam message indicates that a BCC recipient was added, the Office 365 administrator must have configured that address and other settings. Your application can get the list of these actions by getting a MailFilterList report using the $filter=SelectionTarget eq 'Actions' query option. For more information, see the MailFilterList report topic.

Action value	Description
AddBccRecipient	A BCC (Blind Carbon Copy) recipient was added to the message.
AddCcRecipient	A CC (Carbon Copy) recipient was added to the message.
AddManagerAsRecipient	If the sender or recipient is within the organization, and they have a manager specified in their profile, their manager will be added as a To-line recipient. This is done separately for the original sender and recipient, so that there might be two managers added.
AddToRecipient	A recipient was added to the To-line.
ApplyClassification	The message classification was changed.
ApplyHtmlDisclaimer	A disclaimer message was added to the end of the message. The disclaimer format was in HTML.
DeleteMessage	The message was deleted.
GenerateIncidentReport	An incident report was generated and sent to the email administrator.
ModerateMessageByManager	The sender's manager has been asked to approve the message being sent.
ModerateMessageByUser	A specific user was asked to approve the message being sent. This designated user is typically an email administrator.
NotifySender	A separate message was sent to the sender indicating that their message was identified as spam.
PrependSubject	The Subject line was modified with a prefix indicating the message may be spam. For example: "SUSPECT:"
Quarantine	The message was moved to the quarantine mailbox.
RedirectMessage	The original To, CC and BCC recipients were removed, and the message was sent to a different To recipient.
RejectMessage	The mail system that transmitted the message was informed that the message was rejected by Office 365.
RemoveMessageHeader	A message header was removed from the message. The email administrator configures which headers to remove.
RequireTLS	The email system will transmit the message to the the receiving system, and will require that system accept the message encrypted via TLS instead of as plaintext.
RightsProtectMessage	The configured Digital Rights Management (DRM) settings will be applied to the message when it is transmitted.
RouteMessageUsingConnector	The message will be transmitted over the configured messaging connector.
SetAuditSeverityLow, SetAuditSeverityMedium, SetAuditSeverityHigh	The message was transmitted, and the Audit Severity was set on the message.
SetMessageHeader	The configured header was set.
SetSpamConfidenceLevel	A spam confidence level (SCL) header was added to the message.
StopRuleProcessing	Indicates that the Stop Processing spam processing rule was encountered on the message.

SelectionTarget eq ’DlpPolicy’ values

The Display and Value fields of entries having $filter=SelectionTarget eq ’DlpPolicy’ are set by the administrator when they configure the Office 365 data loss prevention (DLP) policies. The administrator defines named policies that are applied as messages are processed through the email system. DLP policies are containers for DLP rules. The category/sub-category relationship between polices and rules is explained at the end of this section. The list of DlpPolicy values is ultimately controlled by the administrator. Examples of policy Display values are: Company Sensitive Data, Financial Data Detection, and HIPAA Detection.

SelectionTarget eq ’DlpRule’ values

The Display and Value fields of entries using $filter=SelectionTarget eq ’DlpRule’ are set by the administrator when they configure the Office 365 DLP policy rules. DLP rules detect some condition in the message and take some action in response, as the messages are processed through the email system. DlpRule entries in the MailFilterList report results are tied to their containing DlpPolicy entries by the ParentTarget and ParentValue field values. The category/sub-category relationship between polices and rules is explained at the end of this section. The list of DlpRule values is ultimately controlled by the administrator. Example of rule Display values are: PII Detection, PCI DSS Detection Rule 1, and Financial Data Detection Rule 1.

SelectionTarget eq ’Domain’ values

The Display and Value fields of entries using $filter=SelectionTarget eq ’Domain’ indicate the domain names associated with the organization. Office 365 supports organizations using multiple authoritative and associated domains, and the Reporting web service can filter report data by domain for reports that include the Domain field.

SelectionTarget eq ’EventTypes’ values

MailFilterList entries that have $filter=SelectionTarget eq ’EventType’ indicate what kind of scanning was performed on the message. The following table lists the other available event types. Remember that these events may require some administrative configuration, and may vary by the organization's subscription options. Your application can get the list of these event types by getting a MailFilterList report using the $filter=SelectionTarget eq 'EventTypes' query option. For more information, see the MailFilterList report topic.

EventTypes value	Description
DLPActionHits	The message triggered a DLP rule to execute.
DLPMessages	The message was being scanned to determine whether it was generated by a DLP rule.
DLPPolicyFalsePositive	The message was examined to determine whether previously-detected DLP policy violations were incorrectly triggered.
DLPPolicyHits	The message was examined to determine whether any DLP policy rules were triggered.
DLPPolicyOverride	Information on the message indicated that one or more DLP policies were overridden for the message.
DLPRuleHits	The message was examined to determine whether any DLP rules were triggered.
GoodMail	The message was being scanned for having originated at a known-good sender.
Malware	The message was being scanned for malware. For example, viruses, ransom-ware, and so on.
SpamContentFiltered	The message was being scanned for indications it is spam, such as unsolicited commercial email message, or a phishing message.
SpamEnvelopeBlock	The message envelope was being scanned for indications it contains spam.
SpamIPBlock	The message was being checked to see if it came from an IP address known to relay or produce spam messages.
TopMailUser	The message recipients and sender were being collected so their tally of mail messages could be updated, for use by the MailTrafficTop report.
TopMalware	A message identified as being malware was tallied for the MailTrafficTop report.
TopMalwareUser	A message identified as containing malware was tallied against the recipients and sender for use in the MailTrafficTop report.
TopSpamUser	A message identified as being spam was tallied against the recipients and sender for use in the MailTrafficTop report.
TransportRuleActions	The message transport history was examined to collect information about the transport rules used to handle it, for use in the MailTrafficTop report.
TransportRuleHits	The message transport history was examined to collect information about the transport rules that were triggered, for use in the MailTrafficTop report.
TransportRuleMessages	The message was being scanned to determine if it was created by a transport rule.

SelectionTarget eq ’TransportRule’ values

The Display and Value fields of entries using $filter=SelectionTarget eq ’TransportRule’ are set by the administrator when they configure the Office 365 DLP policy rules. DLP rules detect some condition in the message and take some action in response, as the messages are processed through the email system. DlpRule entries in the MailFilterList report results are tied to their containing DlpPolicy entries by the ParentTarget and ParentValue field values. The category / sub-category relationship between polices and rules is explained later in this topic. The list of DlpRule values is ultimately controlled by the administrator. Example of rule Display values are: PII Detection, PCI DSS Detection Rule 1, and Financial Data Detection Rule 1.

Understanding the ParentTarget and ParentValue fields

The DLP-related entries form a category/sub-category relationship among the MailFilterList entries where SelectionTarget is DlpPolicy or DlpRule. The following diagram depicts an example relationship consisting of two policies and four rules. PolicyOne uses Rule-A and Rule-B, and PolicyTwo uses Rule-C, Rule-B and Rule-D. Because two different policies include Rule-B, the MailFilterList results include two entries for Rule-B, distinguished by their ParentValue field values, which match the corresponding DlpPolicyValue fields.

Figure 1. Diagram of two policies and four rules.

DlpPolicy and DlpRule category / sub-category

Examples

The following request and response pair demonstrates how to retrieve a MailFilterList report of mail-filtering Actions. For clarity, line-breaks were added to the request, and some Atom XML results were removed from the results.

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailFilterList?
    $select=Display,Domain,Organization,ParentTarget,ParentValue,SelectionTarget&
    $filter=SelectionTarget%20eq%20'Actions'&
    $format=Atom

<?xml version="1.0" encoding="utf-8"?>
<feed xml:base="https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/" 
  xmlns="http://www.w3.org/2005/Atom" xmlns:d="https://schemas.microsoft.com/ado/2007/08/dataservices" 
  xmlns:m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <id>https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailFilterList</id>
  <title type="text">MailFilterList</title>
  <updated>2013-02-08T02:32:05Z</updated>
  <link rel="self" title="MailFilterList" href="MailFilterList" />
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailFilterList('Actions')</id>
    <category term="TenantReporting.MailFilterListReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailFilterListReport" href="MailFilterList('Actions')" />
    <title />
    <updated>2013-02-08T02:32:05Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Organization>example.onmicrosoft.com</d:Organization>
        <d:SelectionTarget>Actions</d:SelectionTarget>
        <d:Display>AddBccRecipient</d:Display>
        <d:ParentTarget m:null="true" />
        <d:ParentValue m:null="true" />
        <d:Domain m:null="true" />
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailFilterList('Actions')</id>
    <category term="TenantReporting.MailFilterListReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailFilterListReport" href="MailFilterList('Actions')" />
    <title />
    <updated>2013-02-08T02:32:05Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Organization>example.onmicrosoft.com</d:Organization>
        <d:SelectionTarget>Actions</d:SelectionTarget>
        <d:Display>AddCcRecipient</d:Display>
        <d:ParentTarget m:null="true" />
        <d:ParentValue m:null="true" />
        <d:Domain m:null="true" />
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailFilterList('Actions')</id>
    <category term="TenantReporting.MailFilterListReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailFilterListReport" href="MailFilterList('Actions')" />
    <title />
    <updated>2013-02-08T02:32:05Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Organization>example.onmicrosoft.com</d:Organization>
        <d:SelectionTarget>Actions</d:SelectionTarget>
        <d:Display>AddManagerAsRecipient</d:Display>
        <d:ParentTarget m:null="true" />
        <d:ParentValue m:null="true" />
        <d:Domain m:null="true" />
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailFilterList('Actions')</id>
    <category term="TenantReporting.MailFilterListReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailFilterListReport" href="MailFilterList('Actions')" />
    <title />
    <updated>2013-02-08T02:32:05Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Organization>example.onmicrosoft.com</d:Organization>
        <d:SelectionTarget>Actions</d:SelectionTarget>
        <d:Display>AddToRecipient</d:Display>
        <d:ParentTarget m:null="true" />
        <d:ParentValue m:null="true" />
        <d:Domain m:null="true" />
      </m:properties>
    </content>
  </entry>

  [[ lines removed for clarity ]]

  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailFilterList('Actions')</id>
    <category term="TenantReporting.MailFilterListReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailFilterListReport" href="MailFilterList('Actions')" />
    <title />
    <updated>2013-02-08T02:32:05Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Organization>example.onmicrosoft.com</d:Organization>
        <d:SelectionTarget>Actions</d:SelectionTarget>
        <d:Display>SetSpamConfidenceLevel</d:Display>
        <d:ParentTarget m:null="true" />
        <d:ParentValue m:null="true" />
        <d:Domain m:null="true" />
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailFilterList('Actions')</id>
    <category term="TenantReporting.MailFilterListReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailFilterListReport" href="MailFilterList('Actions')" />
    <title />
    <updated>2013-02-08T02:32:05Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Organization>example.onmicrosoft.com</d:Organization>
        <d:SelectionTarget>Actions</d:SelectionTarget>
        <d:Display>StopRuleProcessing</d:Display>
        <d:ParentTarget m:null="true" />
        <d:ParentValue m:null="true" />
        <d:Domain m:null="true" />
      </m:properties>
    </content>
  </entry>
</feed>

The following MailFilterList report request and response retrieves the Display field for all domains associated with the Office 365 organization, in JSON format. For clarity, line-breaks were added to the request.

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailFilterList?
    $select=Display&
    $filter=SelectionTarget%20eq%20'Domain'&
    $format=Json

  {
    "d":
      {
        "results":
          [
              {
                "__metadata":
                  {
                    "id":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailFilterList('Domain')",
                    "uri":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailFilterList('Domain')",
                    "type":"TenantReporting.MailFilterListReport"
                  },
                "Display":"example.onmicrosoft.com"
              }
          ]
      } 
  }

Input parameters and report output columns

The [In/Out] indicators in the fields table have the following meanings:

Fields marked [In] in the fields table are primarily intended for use in $filter=, $orderby= and other query options that restrict which entries the report returns. Fields marked [In] in the fields table can be included the $select= option, and they will appear in the report entries, but they will contain no useful data.
Fields marked [In/Out] in the fields table can be used in both column selection ($select=) and entry restriction ($filter= and $orderby=) options. When you include one of these fields in the $select= option, they will appear in the report entries, and will contain useful data when it is available.

Compatibility

The MailFilterList report was introduced in Office 365 service version 2013-V1. For more information on versioning, see Versioning in the Office 365 Reporting web service.

Corresponding PowerShell cmdlets

The MailFilterList report returns the same information as the Get-MailFilterListReport Windows PowerShell cmdlet.

Permissions

The account you access the reports from must have administrative permissions in that Office 365 organization. If the account can view this report in the Office 365 control panel, then the account has permissions to retrieve the data from the REST web service. This report requires the user to be assigned to the View-Only Recipients Role. In the default Office 365 permissions structure, users with the following administrator permissions can access this report: billing administrator, global administrator, password administrator, service administrator, and user management administrator.

Data granularity, persistence, and availability

The information for this report is not time-based. Parts of the data returned by this report are dependent on how the administrator has configured the Office 365 services. This report is available as long as the subscription has not expired.

Share via