> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mainwp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pro Reports

> The MainWP Pro Reports Extension is a fully customizable reporting engine that allows you to create the type of report you are proud to send to your clients.

## What You'll Learn

* Setting up the Pro Reports Extension and Child Reports plugin
* Creating recurring and one-time reports
* Customizing report templates with tokens
* Managing client information and branding

***

> [!NOTE]
>
> **Extension Add-on** - This add-on provides standalone functionality within MainWP Dashboard. No third-party plugins required.

[Pro Reports - Video Tutorial](https://www.youtube.com/embed/4uF7wmvLigA)

The [MainWP Pro Reports Extension](https://mainwp.com/extension/pro-reports/) combines the free [MainWP Child Reports](https://wordpress.org/plugins/mainwp-child-reports/) plugin with a customizable reporting engine. The Child Reports plugin tracks changes on your child sites, while the Pro Reports Extension on your Dashboard gathers that information and converts it to PDF reports.

**Key features:**

* Generate professional reports in seconds
* Pre-made templates to get you started
* Automatic PDF attachment to emails
* Include or exclude specific content
* Customizable template system
* Custom branding options

![Report preview](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-preview.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=1bb571b8665011971c4b4725b3df6d20)

## Setting up the Pro Reports Extension

### Installation

**1. Install MainWP Child Reports**

[Install](https://docs.mainwp.com/sites/plugins/managing-plugins-with-mainwp.md) the [MainWP Child Reports](https://wordpress.org/plugins/mainwp-child-reports/) plugin on all child sites. This free plugin records logging events that appear in your reports. Records are kept for 100 days.

**2. Install Pro Reports Extension**

[Install](https://docs.mainwp.com/dashboard/overview/manage-extensions.md#install-add-ons) the MainWP Pro Reports Extension on your Dashboard.

**3. Sync your sites**

Sync your sites so the Dashboard can detect which sites have the Child Reports plugin installed.

> [!WARNING]
>
> **Reports require recorded activity.** The MainWP Child Reports plugin must collect site data before reports can show meaningful content. After installation, allow several days for the plugin to record events such as updates, posts, and changes. Reports generated immediately after installation will display empty sections.

> [!TIP]
>
> To test Pro Reports with default settings, skip to [Create a One-Time Report](#create-a-one-time-report). Client information and custom branding can be configured later.

## MainWP Child Reports Plugin

The [MainWP Child Reports plugin](https://wordpress.org/plugins/mainwp-child-reports/) records changes on your child sites and communicates them to the Pro Reports Extension. Built on the [Stream Plugin](https://wordpress.org/plugins/stream/), it currently requires PHP 7.4 or higher.

### Viewing Recorded Data

By default, go to **WP Admin > Settings > MainWP Child > Child Reports** on your child site to see recorded activity. If you have customized MainWP Child branding, these labels can differ.

![Child reports data](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-activity-log.jpg?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=cdf00a8dff1acf0aa4a02de660e8ee6e)

### Child Reports Settings

![Child Reports settings](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-child-settings.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=cf53ae0abf60a75d587c632c5b92ddbf)

By default, navigate to **WP Admin > Settings > MainWP Child > Child Reports Settings** to configure the plugin. If you have customized MainWP Child branding, these labels can differ.

| Setting | Description |
| - | - |
| Keep Records for | Maximum days to retain activity records (default: 100) |
| Keep Records Indefinitely | Retains all records (not recommended for performance) |
| Comment Flood Tracking | Track duplicate comments blocked by WordPress (not recommended) |
| Akismet Tracking | Track comment spam attempts blocked by Akismet when Akismet is active |
| WP Cron Tracking | Track WordPress cron event activity when WP-Cron is enabled |
| Reset MainWP Child Reports Database | Delete all activity reports from the database |

### Client Information

Pro Reports uses tokens to personalize reports without creating separate versions for each client. Tokens are placeholders like `[client.email]` and `[client.name]` that get replaced with actual values when reports generate. You can define client information in two ways:

| Method | Description | Best For |
| - | - | - |
| Client Feature | Define information once, assign multiple sites to a client | Managing many sites per client |
| Per-Site Settings | Set information individually on each site's Edit page | Maximum flexibility |

> [!NOTE]
>
> When the same token is defined in both locations, the per-site value takes priority.

#### Setting Per-Site Client Information

**1. Navigate to site settings**

Go to **MainWP Dashboard > Sites > Manage Sites** and click **Edit** on the desired site.

**2. Configure tokens**

Locate the **Pro Reports Tokens** section and enter values for tokens you plan to use.

![Pro report tokens](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-tokens-form.jpg?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=73a85ea6852990ef63c05a04aadf7497)

**3. Save settings**

Click **Save Settings**.

> [accordion] Token Configuration
>
> > [card] [Client vs Site Tokens](https://docs.mainwp.com/add-ons/agency/difference-between-client-level-and-site-level-custom-tokens.md)
> >
> > Understand token priority and when to use each level.

## Report Types

Pro Reports offers two report formats. Recurring reports run on a schedule you define. One-time reports cover a specific date range you select manually.

| Aspect | Recurring | One-Time |
| - | - | - |
| Schedule | Daily, Weekly, or Monthly | None (manual send) |
| Date Range | Automatic based on schedule | Custom start and end dates |
| Action | Schedule Report | Send Now |
| Use Case | Ongoing client updates | Project completion, audits |

## Create a Recurring Report

**1. Open Create Report**

Go to **MainWP Dashboard > Add-ons > Pro Reports > Create Report**.

**2. Configure report settings**

![Create report](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-create-page.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=8084cae5c5f197e13021f08f8627dd08)

| Setting | Description |
| - | - |
| Report title | Name for identifying this report |
| Report type | Select **Recurring** |
| Schedule | Daily, Weekly, or Monthly |
| Send report on | Day of week or month (for Weekly/Monthly schedules) |
| Report PDF file name | Optional custom filename for the PDF attachment |
| Report Template | Select from available templates |

**3. Customize content and design**

![Report settings](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-custom-content.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=032d16eee94b006e91a53c464b1a68be)

| Tab | Purpose |
| - | - |
| Custom Content | Set the report heading shown on the first page and write the introduction and closing message. All three fields support tokens, and the introduction and closing message use the visual editor so you can add formatted client-facing copy. |
| Report Data | Control which sections appear in the report and whether each one is set to **Show**, **Hide**, or **Hide if empty**. This includes core report areas such as WordPress, plugin and theme updates, posts, pages, users, comments, and uptime, plus any compatible add-on data currently active on your Dashboard such as backups, analytics, monitoring, security, performance, and maintenance sections. The **Backups** section appears when at least one selected site uses [API Backups](https://docs.mainwp.com/sites/backups/api-backups.md) or has a supported backup add-on active (BackWPup, BackupWordPress, Solid Backups, or UpdraftPlus). |
| Custom Branding | Upload your logo and an optional first-page header image, then set the first-page background, page background, text, accent, link, and table colors. Use this tab to match the PDF layout to your brand. |
| Custom Titles | Rename or translate report titles, subtitles, and table headings for the sections included in the report. These overrides are saved per report, which lets you keep different client-facing wording or language versions. It changes the labels in the report, but not the actual data values returned by WordPress, themes, plugins, or other integrations. |

**4. Configure email settings**

| Field | Description |
| - | - |
| Send email from | Your email address and name |
| Send email to | Client email and name (supports tokens like `[client.email]`) |
| Reply-to | Optional reply address |
| Email subject | Subject line (supports tokens) |
| Email message | Email body (supports tokens) |
| Email template | Select template style |
| BCC email address | Optional blind copy recipient |
| Additional attachments | Optional extra files |

**5. Select sites and schedule**

Select sites in the right-hand metabox. Preview as HTML or download the PDF for review. Click **Save Draft** to save without scheduling, or **Schedule Report** when ready.

![Report site selection](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-recurring-settings.gif?s=fa3ae9a089dc361715c3a073958fb505)

## Create a One-Time Report

**1. Open Create Report**

Go to **MainWP Dashboard > Add-ons > Pro Reports > Create Report**.

**2. Configure report settings**

![One time report](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-onetime-settings.gif?s=69ed8115b6e785202681aa5b3a27dbcc)

| Setting | Description |
| - | - |
| Report title | Name for identifying this report |
| Report type | Select **One-time** |
| Report date range | Starting and ending dates |
| Report PDF file name | Optional custom filename |
| Report Template | Select from available templates |

**3. Customize content and design**

![Report data settings](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-custom-content.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=032d16eee94b006e91a53c464b1a68be)

| Tab | Purpose |
| - | - |
| Custom Content | Set the report heading shown on the first page and write the introduction and closing message. All three fields support tokens, and the introduction and closing message use the visual editor so you can add formatted client-facing copy. |
| Report Data | Control which sections appear in the report and whether each one is set to **Show**, **Hide**, or **Hide if empty**. This includes core report areas such as WordPress, plugin and theme updates, posts, pages, users, comments, and uptime, plus any compatible add-on data currently active on your Dashboard such as backups, analytics, monitoring, security, performance, and maintenance sections. The **Backups** section appears when at least one selected site uses [API Backups](https://docs.mainwp.com/sites/backups/api-backups.md) or has a supported backup add-on active (BackWPup, BackupWordPress, Solid Backups, or UpdraftPlus). |
| Custom Branding | Upload your logo and an optional first-page header image, then set the first-page background, page background, text, accent, link, and table colors. Use this tab to match the PDF layout to your brand. |
| Custom Titles | Rename or translate report titles, subtitles, and table headings for the sections included in the report. These overrides are saved per report, which lets you keep different client-facing wording or language versions. It changes the labels in the report, but not the actual data values returned by WordPress, themes, plugins, or other integrations. |

**4. Configure email settings**

| Field | Description |
| - | - |
| Send email from | Your email address and name |
| Send email to | Client email and name (supports tokens) |
| Reply-to | Optional reply address |
| Email subject | Subject line (supports tokens) |
| Email message | Email body (supports tokens) |
| Email template | Select template style |
| BCC email address | Optional blind copy recipient |
| Additional attachments | Optional extra files |

**5. Select sites and send**

Select sites in the right-hand metabox. Preview as HTML or download the PDF for review. Click **Save Draft** to save without sending, or **Send Now** when ready.

![Report sites selection](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-site-selection.gif?s=4baa5585a131319583e78c1b1b77c54b)

> [accordion] Email Customization
>
> > [card] [Custom Email Logo](https://docs.mainwp.com/add-ons/agency/how-to-use-a-different-logo-for-the-pro-reports-email-only.md)
> >
> > Use a different logo in email body versus PDF attachment.
>
> > [card] [Custom Email Template](https://docs.mainwp.com/add-ons/agency/create-a-custom-pro-reports-email-template.md)
> >
> > Copy a built-in email template, edit it, upload it, and use it in your report.
>
> > [card] [HTML-Only Reports](https://docs.mainwp.com/add-ons/agency/how-to-create-an-html-only-report-using-the-pro-reports-extension.md)
> >
> > Send reports as HTML email without PDF attachments.

## Background Delivery and Recovery

> [!NOTE]
>
> This section applies to a Pro Reports build that includes background delivery and the Pro Reports Abilities API. Earlier builds use the existing report workflow. Check [ability discovery](https://docs.mainwp.com/api-reference/abilities-api/pro-reports.md#access-and-availability) before using automation.

### Check Each Site's Result

A report request can be accepted before generation and sending finish. The progress dialog follows the background run and reports results for each selected site. Check those results before starting another send. One failed site does not mean every site failed.

**Accepted for sending** means the local mail system accepted the message. It does not confirm delivery to the client's inbox. If the dialog reports an unknown or uncertain email outcome, sending may already have happened. Pro Reports does not automatically retry an unknown handoff. Check your mail delivery records before requesting another send.

Automation clients can [read a run and its per-site deliveries](https://docs.mainwp.com/api-reference/abilities-api/pro-reports.md#check-a-run) without sending again. Reuse the original request reference for an identical retry after a lost response; a new reference can start another send.

Keep WordPress cron or your existing server cron runner working so queued generation and delivery can continue. Background report tasks appear in MainWP's cron schedule list.

### Review Existing Reports After an Update

Existing report templates, sharing, and schedules are retained. An older report can still use the editor and its schedule without appearing in the Abilities definition list. Saving or scheduling it explicitly can create its automation definition.

If a report shows **Needs review**, open it and check its recipients, selected sites, and schedule before saving. If it shows **Paused** because site access could not be confirmed, verify access to the selected sites and save the schedule to resume automatic reports.

### Resolve Delivery Storage or Permission Notices

If you see **Report abilities are unavailable because delivery storage is not ready**, ask your database administrator to check that the report tables and WordPress options table use InnoDB. Existing legacy reports can still be previewed, downloaded, and sent through the existing interface. Pro Reports does not automatically convert existing tables.

Report changes, generation, sending, schedule changes, and run management require **Pro Reports Management**, in addition to Pro Reports access and access to the report's sites. If an action is refused, have the Dashboard administrator review those permissions in [Team Control](https://docs.mainwp.com/add-ons/agency/team-control-extension.md).

## Pro Reports Dashboard

![MainWP Child Reports Overview](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-child-dashboard.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=af33ec77e26a6c157e94c6a2f9b7f0c6)

The **MainWP > Add-ons > Pro Reports > Child Reports Dashboard** page monitors all child sites with the MainWP Child Reports plugin installed.

### Status Indicators

| Row Color | Meaning | Available Action |
| - | - | - |
| Red | Plugin not activated | Activate |
| Yellow | Update available | Update |
| Normal | Plugin active and current | Hide/Unhide |

### Dashboard Columns

| Column | Description |
| - | - |
| Version | MainWP Child Reports plugin version |
| Last Report | When the last report was sent |
| Reports DB Size | Database space used by reports |

Bulk actions for Activate, Update, Hide, and Unhide are available at the top of the page. If a site with the plugin installed does not appear, re-sync your sites.

## Create Custom Report Templates

[Pro Reports - Video Tutorial](https://www.youtube.com/embed/1qLxJz1-5RI)

Pro Reports uses PHP templates that you can customize with HTML. The process involves copying a built-in template and modifying it to suit your needs.

### Creating a Custom Template

**1. Download the add-on**

[Download the MainWP Pro Reports Extension](https://docs.mainwp.com/dashboard/overview/manage-extensions.md) from your MainWP Account.

**2. Extract and locate templates**

Extract the plugin files and find the default templates in `/mainwp-pro-reports-extension/templates/reports/`.

**3. Copy and customize**

Copy a PHP file, rename it, and edit with your preferred code editor.

**4. Upload the template**

Upload your customized PHP file to `/wp-content/uploads/mainwp/report-templates/` on your Dashboard site.

**5. Select the template**

Your template appears in the **Report template** dropdown.

![Report template selection](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-template-dropdown.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=222835f26604b691e0aa0636b0ef0946)

> [accordion] Template Resources
>
> > [card] [Custom Templates Guide](https://docs.mainwp.com/add-ons/agency/create-custom-report-templates.md)
> >
> > Build custom PHP templates from scratch with detailed token placement.
>
> > [card] [Add Images to Templates](https://docs.mainwp.com/add-ons/agency/how-to-add-images-to-custom-pro-report-templates.md)
> >
> > Insert custom images and graphics into your report templates.
>
> > [card] [Limit Table Entries](https://docs.mainwp.com/add-ons/agency/limit-the-amount-of-table-entries-in-the-pro-report-sections.md)
> >
> > Control how many rows appear in report sections using CSS.

### Token Types

Pro Reports uses four token types that you can add directly to PHP templates or through the visual editor.

| Type | Description | Example |
| - | - | - |
| Client Tokens | Display data from Individual Child site settings | `[client.email]`, `[client.name]` |
| Section Tokens | Loop through database records within a date range | `[section.plugins.installed]...[/section.plugins.installed]` |
| Data Tokens | Display specific values inside section tokens | `[plugin.name]`, `[plugin.installed.date]` |
| Counter Tokens | Display counts outside section tokens | `[plugin.installed.count]` |

See all available tokens: [Available Pro Reports Tokens](https://docs.mainwp.com/add-ons/agency/available-pro-reports-tokens.md)

### Client Tokens

Client tokens display data set in the Individual Child site Edit tab. Set values for tokens you plan to use in reports.

![Site token values](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-site-tokens.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=3260ee187e8d6aec431a2eb656d26b0c)

Use `[client.email]` in the **Send email to** field to send reports to multiple clients automatically.

![Email settings](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-email-settings.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=2c32c2dbdaad792dfceeea144c27f899)

Click **Insert tokens** to see available options.

![Field tokens](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-available-tokens.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=87a3af58371611671a9d784dd29cb1e9)

### How Tokens Work Together

The following example demonstrates all three token types working together in a template:

```
Plugins installed: [plugin.installed.count]

[section.plugins.installed]
  Plugin: [plugin.name]
  Installed: [plugin.installed.date]
[/section.plugins.installed]
```

**Counter tokens** display totals and must appear outside section tags. They end with `.count`.

**Section tokens** loop through database records within the report date range. They require opening and closing tags.

**Data tokens** display specific values and must appear between section token tags.

![Report data preview](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-plugins-list.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=9edd3a3d111cf05daaa2678fa1aff4bf)

![Template tokens](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-token-reference.png?fit=max\&auto=format\&n=fe8MDk8Na8l3lQHZ\&q=85\&s=727ea5e785568e2108a0c52cec0b153d)

> [accordion] Token Reference
>
> > [card] [Available Tokens](https://docs.mainwp.com/add-ons/agency/available-pro-reports-tokens.md)
> >
> > Complete reference of 100+ tokens for plugins, themes, posts, users, and more.
>
> > [card] [Conditional Messages](https://docs.mainwp.com/add-ons/agency/conditional-messages-in-pro-reports.md)
> >
> > Use PHP filters to display dynamic messages based on data values.

## Delete Reports

![Delete report](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-delete-report.gif?s=123cb2c49a2b71ba6063e2cc6c84e5e0)

**1. Navigate to reports**

Go to **MainWP > Add-ons > Pro Reports > Reports**.

**2. Delete the report**

Click the Actions Menu on the report you want to delete, select **Delete**, and confirm.

## Duplicate Reports

![Duplicate report](https://mintcdn.com/mainwp/fe8MDk8Na8l3lQHZ/images/add-ons/pro-reports-duplicate-report.gif?s=be8b49df7f04aac5578b98e2f1038f04)

**1. Navigate to reports**

Go to **MainWP > Add-ons > Pro Reports > Reports**.

**2. Duplicate the report**

Click the Actions Menu, select **Duplicate**, enter a new title, configure Send To and Send From fields, and click **Save Draft**.

## PDF Storage

Earlier Pro Reports builds save PDFs on the Dashboard site in `/wp-content/uploads/mainwp_pro_reports/`. Builds with background delivery keep run artifacts in private storage and serve previews and downloads through authorized report actions. Use the report controls instead of relying on a direct file URL.

## Pro Reports Abilities API

Use the [Pro Reports Abilities reference](https://docs.mainwp.com/api-reference/abilities-api/pro-reports.md) to discover eleven abilities for report definitions, catalogs, generation, sending, schedules, and delivery outcomes. Changes use a preview and confirmation; accepted background work must be checked for completion.

## Pro Reports REST API

All MainWP REST API calls, including documentation and examples, are available on [Postman](https://www.postman.com/mainwp/workspace/mainwp/overview). See [MainWP REST API](https://docs.mainwp.com/api-reference/rest-api/overview.md) for details on enabling the API and managing keys.

***

## Related Resources

* [Create Custom Report Templates](https://docs.mainwp.com/add-ons/agency/create-custom-report-templates.md) - Build custom templates
* [Create a custom Pro Reports email template](https://docs.mainwp.com/add-ons/agency/create-a-custom-pro-reports-email-template.md) - Copy and customize a built-in email template
* [Available Pro Reports Tokens](https://docs.mainwp.com/add-ons/agency/available-pro-reports-tokens.md) - Token reference
* [Agency Add-ons](https://docs.mainwp.com/add-ons/agency.md) - Browse agency add-ons


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.