Reports

Note

The content for this page requires a major update. The legacy page contains outdated and potentially inaccurate information. You can still access it in the Mautic Developer Documentation archived repository.

If you’re interested in helping develop the new content for this page and others, consider joining the documentation efforts.

Please read the Contributing Guidelines and Contributing to Mautic’s documentation to get started.

Use this endpoint to obtain details on Mautic’s Reports.

Using Mautic’s API Library

You can interact with this API through the Mautic API Library as follows, or use the various http endpoints as described in this document.

<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth  = new ApiAuth();
$auth      = $initAuth->newAuth($settings);
$apiUrl    = "https://example.com";
$api       = new MauticApi();
$reportApi = $api->newApi("reports", $auth, $apiUrl);

Get report

<?php

//...
// Get all with default options:
$report = $reportApi->get($id);

// Or define exactly what rows you want:
$limit    = 100;
$page     = 2;
$dateFrom = \DateTime('1 week ago');
$dateTo   = \DateTime('now');
$report   = $reportApi->get($id, $limit, $page, $dateFrom, $dateTo);

Get an individual Report by ID.

HTTP Request

GET /reports/ID

Or define query parameters like this:

GET /reports/3?dateFrom=2017-01-01&dateTo=2018-01-01&limit=5&page=3

Response

Expected Response Code: 200

{

“totalResults”: 3990, “data”: [

{
“id2”: “12”, “email1”: “john@example.com”, “firstname1”: “”, “lastname1”: “”

}, {

“id2”: “23”, “email1”: “alex@example.com”, “firstname1”: “”, “lastname1”: “”

}, {

“id2”: “24”, “email1”: “amal@example.com”, “firstname1”: “”, “lastname1”: “”

}, {

“id2”: “25”, “email1”: “ariel@example.com”, “firstname1”: “”, “lastname1”: “”

}, {

“id2”: “26”, “email1”: “bola@example.com”, “firstname1”: “”, “lastname1”: “”

}

], “dataColumns”: {

“address11”: “l.address1”, “address21”: “l.address2”, “attribution1”: “l.attribution”, “attribution_date1”: “l.attribution_date”, “city1”: “l.city”, “company1”: “l.company”, “companyaddress11”: “comp.companyaddress1”, “companyaddress21”: “comp.companyaddress2”, “companycity1”: “comp.companycity”, “companyemail1”: “comp.companyemail”, “companyname1”: “comp.companyname”, “companycountry1”: “comp.companycountry”, “companydescription1”: “comp.companydescription”, “companyfax1”: “comp.companyfax”, “id1”: “comp.id”, “companyphone1”: “comp.companyphone”, “companystate1”: “comp.companystate”, “companywebsite1”: “comp.companywebsite”, “companyzipcode1”: “comp.companyzipcode”, “id2”: “l.id”, “country1”: “l.country”, “custom_select1”: “l.custom_select”, “date_identified1”: “l.date_identified”, “email1”: “l.email”, “facebook1”: “l.facebook”, “fax1”: “l.fax”, “firstname1”: “l.firstname”, “foursquare1”: “l.foursquare”, “gender1”: “l.gender”, “googleplus1”: “l.googleplus”, “ip_address1”: “i.ip_address”, “instagram1”: “l.instagram”, “is_primary1”: “companies_lead.is_primary”, “lastname1”: “l.lastname”, “linkedin1”: “l.linkedin”, “mobile1”: “l.mobile”, “multiline1”: “l.multiline”, “multiselect1”: “l.multiselect”, “owner_id1”: “l.owner_id”, “first_name1”: “u.first_name”, “last_name1”: “u.last_name”, “phone1”: “l.phone”, “points1”: “l.points”, “position1”: “l.position”, “preferred_locale1”: “l.preferred_locale”, “timezone1”: “l.timezone”, “skype1”: “l.skype”, “state1”: “l.state”, “title1”: “l.title”, “twitter1”: “l.twitter”, “website1”: “l.website”, “zipcode1”: “l.zipcode”,

}, “limit”: 5, “page”: 3, “dateFrom”: “2017-01-01T00:00:00+00:00”, “dateTo”: “2018-10-24T11:55:29+00:00”,

}

Report Properties

- Name
  - Type
  - Description
- - totalResults
  - int
  - 在定义的日期范围内返回的结果数量。默认日期范围是从30天前到现在。
- - data
  - array
  - 包含与每个报告的数据类型和选定的列相关的行。
- - dataColumns
  - array
  - 报告数据类型的支持的列名数组。
- - limit
  - int
  - 当前应用的限制。
- - page
  - int
  - 当前应用的“页码”。
- - dateFrom
  - datetime
  - 当前应用的日期范围起始过滤条件。
- - dateTo
  - datetime
  - 当前应用的日期范围结束过滤条件。

列出报告

<?php

//...
$reports = $reportApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

返回用户可用的联系人报告列表。此列表不可过滤。

HTTP 请求

GET /reports

响应

预期响应代码：200

{
  "total": 8,
  "reports":[
    {
      "id": 1,
      "name": "Contacts",
      "descriptionn": "lists all contacts",
      "system": false,
      "isScheduled": false,
      "source": "leads",
      "columns": [
        "l.id",
        "l.email",
        "l.firstname",
        "l.lastname"
      ],
      "filters": [],
      "tableOrder": [],
      "graphs": [],
      "groupBy": [],
      "settings": {
        "showGraphsAboveTable": 0,
        "showDynamicFilters": 0,
        "hideDateRangeFilter": 0
      },
      "aggregators": [],
      "scheduleUnit": null,
      "toAddress": null,
      "scheduleDay": null,
      "scheduleMonthFrequency": null
    },
  ]
}

报告属性

- Name
  - Type
  - Description
- - id
  - int
  - ID of the Report
- - name
  - string
  - The Report name
- - description
  - string
  - The Report description
- - system
  - boolean
  - If true then the Report is visible to all Users. If false then only creator can see this Report
- - isScheduled
  - boolean
  - Scheduled Reports send Report Emails as the User defines
- - source
  - string
  - Report data source type
- - columns
  - array
  - List of selected columns for this particular Report
- - filters
  - array
  - Filters applied on this Report
- - tableOrder
  - array
  - Ordering applied on this Report
- - graphs
  - array
  - Graphs defined for this Report. API won’t return graphs
- - groupBy
  - array
  - Group by rules applied for this Report
- - settings
  - array
  - Additional settings for the UI layout
- - aggregators
  - array
  - Aggregation rules applied on this Report
- - scheduleUnit
  - string or null
  - Unit for the scheduler
- - toAddress
  - string or null
  - Email address for the scheduler
- - scheduleDay
  - string or null
  - Day for the scheduler
- - scheduleMonthFrequency
  - string or null
  - Frequency for the scheduler

Create Report

<?php

 $data = array(
     "name" => "New Report",
     "description" => "A new report",
     "system" => true,
     "isScheduled" => false,
     "source" => "email.stats",
     "columns" => array(
         "es.date_sent",
         "es.date_read",
         "e.subject",
         "es.email_address",
         "e.id"
     ),
     "filters" => array(
         array(
             "column" => "e.is_published",
             "condition" => "eq",
             "value" => "1"
         )
     ),
     "tableOrder" => array(
         array(
             "column" => "es.date_sent",
             "direction" => "ASC"
         )
     ),
     "graphs" => array(
         "mautic.email.graph.line.stats",
         "mautic.email.graph.pie.ignored.read.failed",
         "mautic.email.table.most.emails.read",
         "mautic.email.table.most.emails.sent",
         "mautic.email.table.most.emails.read.percent",
         "mautic.email.table.most.emails.failed"
     ),
     "groupBy" => null,
     "settings" => array(),
     "scheduleUnit" => null,
     "toAddress" => null,
     "scheduleDay" => null,
     "scheduleMonthFrequency" => null
 );

 $report = $reportApi->create($data);

Create a new Report.

HTTP Request

POST /reports/new

POST parameters

- Name
  - Type
  - Description
- - name
  - string
  - The Report name
- - description
  - string
  - The Report description
- - system
  - boolean
  - If true then the Report is visible to all Users. If false then only creator can see this Report
- - isScheduled
  - boolean
  - Scheduled Reports send Report Emails as the User defines
- - source
  - string
  - Report data source type
- - columns
  - array
  - List of selected columns for this particular Report
- - filters
  - array
  - Filters applied on this Report
- - tableOrder
  - array
  - Ordering applied on this Report
- - graphs
  - array
  - Graphs defined for this Report. API won’t return graphs
- - groupBy
  - array
  - Group by rules applied for this Report
- - settings
  - array
  - Additional settings for the UI layout
- - aggregators
  - array
  - Aggregation rules applied on this Report
- - scheduleUnit
  - string or null
  - Unit for the scheduler
- - toAddress
  - string or null
  - Email address for the scheduler
- - scheduleDay
  - string or null
  - Day for the scheduler
- - scheduleMonthFrequency
  - string or null
  - Frequency for the scheduler

Response

Expected Response Code: 201

{
 "report":
     {
         "id": 13,
         "name": "Brand New Report",
         "description": "A new report",
         "system": true,
         "isScheduled": true,
         "source": "email.stats",
         "columns": [
             "es.date_sent",
             "es.date_read",
             "e.subject",
             "es.email_address",
             "e.id"
         ],
         "filters": [],
         "tableOrder": [
             {
                 "column": "es.date_sent",
                 "direction": "ASC"
             }
         ],
         "graphs": [
             "mautic.email.graph.line.stats",
             "mautic.email.graph.pie.ignored.read.failed",
             "mautic.email.table.most.emails.read",
             "mautic.email.table.most.emails.sent",
             "mautic.email.table.most.emails.read.percent",
             "mautic.email.table.most.emails.failed"
         ],
         "groupBy": [],
         "settings": {
             "showGraphsAboveTable": null,
             "showDynamicFilters": null,
             "hideDateRangeFilter": null
         },
         "aggregators": [],
         "scheduleUnit": "DAILY",
         "toAddress": "test2@mailinator.com",
         "scheduleDay": null,
         "scheduleMonthFrequency": null
     }
 }

Report Properties

Properties

Same as List Reports.

Edit Report

<?php

$id = 1;

$data = array(: ‘name’ => ‘Updated Report’

);

// 如果 ID 为 1 的报告未找到，是否创建新的报告？ $createIfNotFound = true;

$report = $reportApi->edit($id, $data, $createIfNotFound);

编辑现有报告。请注意，这支持 PUT 或 PATCH，具体取决于所需的行为。

PUT：如果给定 ID 不存在，则会创建一个报告，并清除所有报告信息，然后添加来自请求的信息。 PATCH：如果具有给定 ID 的报告不存在，则操作将失败，并且会使用来自请求的值更新报告字段值。

HTTP 请求

要编辑一个报告，并在未找到该报告时返回 404 错误：

PATCH /reports/ID/edit

要编辑一个报告，如果未找到该报告，则创建一个新的报告：

PUT /reports/ID/edit

POST 参数

Name	Type	Description
`name`	string	报告名称
`description`	string	报告描述
`system`	boolean	如果为 true，则该报告对所有用户可见。如果为 `false`，则只有创建者才能看到此报告。
`isScheduled`	boolean	定时报告会根据用户的定义发送报告邮件。
`source`	string	报告数据源类型
`columns`	array	此特定报告中选择的列列表
`filters`	array	应用于此报告的过滤器
`tableOrder`	array	应用于此报告的排序规则
`graphs`	array	为此报告定义的图表。API 不会返回图表。
`groupBy`	array	应用于此报告的分组规则
`settings`	array	用于 UI 布局的附加设置
`aggregators`	array	应用于此报告的聚合规则
`scheduleUnit`	string or null	调度器的单位
`toAddress`	string or null	调度器的电子邮件地址
`scheduleDay`	string or null	调度器的日期
`scheduleMonthFrequency`	string or null	调度器的频率

响应

如果使用 PUT，则预期的响应代码为 ``200``（如果编辑报告）或 ``201``（如果创建报告）。

如果使用 PATCH，则预期的响应代码为 200。

{

“report”:

{

“id”: 13, “name”: “Brand New Report”, “description”: “A new report”, “system”: true, “isScheduled”: true, “source”: “email.stats”, “columns”: [

“es.date_sent”, “es.date_read”, “e.subject”, “es.email_address”, “e.id”

], “filters”: [], “tableOrder”: [

{
“column”: “es.date_sent”, “direction”: “ASC”

}

], “graphs”: [

“mautic.email.graph.line.stats”, “mautic.email.graph.pie.ignored.read.failed”, “mautic.email.table.most.emails.read”, “mautic.email.table.most.emails.sent”, “mautic.email.table.most.emails.read.percent”, “mautic.email.table.most.emails.failed”

], “groupBy”: [], “settings”: {

“showGraphsAboveTable”: null, “showDynamicFilters”: null, “hideDateRangeFilter”: null

}, “aggregators”: [], “scheduleUnit”: “DAILY”, “toAddress”: “test2@mailinator.com”, “scheduleDay”: null, “scheduleMonthFrequency”: null

}

Properties

Same as List Reports.

Delete Report

<?php

$report = $reportApi->delete($id);

Delete a Report.

HTTP Request

DELETE /reports/ID/delete

Response

Expected Response Code: 200

Properties

Same as List Reports.