MailFilterList report

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.

*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.

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.

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.

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.

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.