Email reports

Stats3x can email a traffic report every day, once a week or once a month. The emails are sent by the Vestnik component - it has to be installed separately.

How it works

Stats3x does not send emails itself. It calculates the numbers and passes them to Vestnik, and Vestnik builds the email from its template, puts it in the queue and sends it. Without Vestnik all other statistics work, only reports are not sent. Step by step:

1. Once an hour the Stats3x cron task "Email report via Vestnik" checks whether it is time to send: sending is enabled, recipients are set, the period has ended, it is 7:00 or later and the report for this period has not been sent yet.
2. If it is time, Stats3x calculates the numbers for the past period and for the same period before it (for comparison), builds the tables of pages, sources and goals and fires the Vestnik event stats3x.report - once for each address from the stats3x.vestnik_recipients setting.
3. Vestnik finds the rule with the stats3x.report event key, takes its template, fills in the placeholders and puts the finished email in the queue (Extras → Vestnik → Queue tab). The email is built at this moment: if you change the template later, emails already in the queue do not change.
4. The Vestnik cron - a separate cron job - sends the queued emails once a minute through MODX mail: via SMTP if it is enabled in the system settings, otherwise with the server mail() function.
5. The result of each sending is on the Vestnik Log tab: Sent, or Failed with the error text. A failed sending is retried on the next Vestnik cron runs; after vestnik_max_attempts attempts (3 by default) the email goes to the log as failed.

Step-by-step setup

1. Install the Vestnik component with the Package Installer. Until it is installed, the "Email reports" card on the State tab says that Vestnik is not installed.
2. Make sure the site can send mail. Emails are sent by MODX: for SMTP fill in the system settings mail_use_smtp, mail_smtp_hosts, mail_smtp_port, mail_smtp_prefix (ssl or tls), mail_smtp_auth, mail_smtp_user and mail_smtp_pass. The sender address is the Vestnik setting vestnik_from_email (empty - emailsender), the name is vestnik_from_name (empty - site_name). The sender must be on the site domain, otherwise emails end up in spam.
3. Add the Vestnik cron - it sends the queued emails. This is a second job, in addition to the Stats3x cron:

   * * * * * php /path/to/site/core/components/vestnik/cron.php > /dev/null 2>&1

4. In the system settings (namespace stats3x, area "Email reports (Vestnik)") set the recipients in stats3x.vestnik_recipients - addresses separated by commas or new lines - and choose how often to send in stats3x.vestnik_period: daily, weekly or monthly.
5. Test the sending: State tab → "Email reports" card → "Send report now" button. On the first click Stats3x creates the template and the rule in Vestnik itself (see below). Below the button you will see how many emails were queued. The Vestnik cron sends them within a minute; not to wait - Extras → Vestnik → Queue → "Process queue". The result is on the Log tab.
6. When the test email has arrived, enable the schedule: stats3x.vestnik_enabled = Yes. The button works with the setting off too, so you can test and design the report in advance.

What Stats3x creates in Vestnik

On the first sending (by the button or on schedule), if they do not exist yet:

• Template "Stats3x: traffic report" (Templates tab): subject "[[+site_name]] statistics for [[+period]]", body - a ready HTML email from the file core/components/stats3x/elements/email/report.language.tpl. The language is the manager language at the moment of creation (ru, en, de, es, pt, en for others).
• Rule "Stats3x: email report" (Rules tab): event key stats3x.report, source "Component event", recipient strategy "Event user", empty recipient value, channel email, the template above.

The "Event user" strategy means the address is taken from the event data: Stats3x fires the event separately for each recipient and passes the address in the email field. That is why recipients are changed only in the stats3x.vestnik_recipients setting. Do not switch the rule strategy to "Explicit address", "Administrator" or "User group" and do not create a second rule for stats3x.report: every event call would send the email to all addresses of such a rule, and recipients would get several copies.

Stats3x never overwrites the template and the rule - change them as you like. To restore the original template, delete it in Vestnik: on the next sending Stats3x creates it again and links it to the rule (if you delete the rule too, both are created). A template in another language: copy the body from the report.en.tpl file (de, es, pt, ru) into it, or delete the template, switch the manager language and click "Send report now". A disabled rule or template stops the reports: Vestnik does not queue emails, the button tells you so, and the cron task retries every hour.

Template placeholders

Stats3x passes this data to the event, you can use it in the subject and body of the Vestnik template. Numbers are already formatted. Everything that came from visitors (page titles, sites, UTM tags) is already escaped - no need to add :htmlent.

The *_html and *_delta placeholders are ready HTML with inline styles (email clients do not support external CSS). Insert them into the template as is.

Example: your own email template

Open Extras → Vestnik → Templates tab → "Stats3x: traffic report", change the subject and body and save. For example, a short email instead of the standard one:

<h2 style="margin:0">[[+site_name]]</h2>
<p style="color:#64748b">Statistics for [[+period]]</p>
<p>
  Visitors: <b>[[+visitors]]</b> [[+visitors_delta]]<br>
  Visits: <b>[[+visits]]</b> [[+visits_delta]]<br>
  Page views: <b>[[+hits]]</b> [[+hits_delta]]<br>
  Bounces: <b>[[+bounce_rate]]</b> [[+bounce_rate_delta]]
</p>
<h3>Top pages</h3>
[[+pages_html]]
[[+goals_html:notempty=`<h3>Goals</h3>[[+goals_html]]`]]
<p><a href="[[+report_url]]">Open statistics</a></p>

The email subject is a template too, for example:

[[+site_name]]: [[+visitors]] visitors for [[+period]]

• A conditional block: [[+goals_html:notempty=`...`]] is output only if the placeholder is not empty.
• The sender of this email is set by the "From (email)" and "From (name)" fields of the template; if they are empty, the Vestnik settings are used.
• The standard template in all languages is in core/components/stats3x/elements/email/ - a good starting point.

Important: "Send test" in the Vestnik template editor fills in its own sample data (name, email, order number) - there are no statistics numbers, and the report placeholders in the test email will be empty. To see the email with real numbers, click "Send report now" on the Stats3x State tab and open the email in Vestnik: Queue → "View email" (while it is not sent yet) or Log → "View" (after sending).

When the report arrives

• daily - every day, for yesterday.
• weekly (default) - on Mondays, for the last week from Monday to Sunday.
• monthly - on the 1st, for the last month.

The report is queued on the first task run after 7:00 in the site time zone (date_timezone): by then the totals of the previous day are recalculated. The task runs once an hour, so the email arrives between 7:00 and 8:00. The report for each period is sent once; if cron did not work on the right day, the report is sent on the first run later, until the next period ends. The numbers are compared with the same number of days right before the period: a week with the week before, yesterday with the day before.

The "Send report now" button sends the report for the last finished period immediately, at any time and as many times as you like. It does not affect the schedule: the scheduled report for this period still arrives.

Run the task from the console - with the same checks as on schedule (not before 7:00 and not twice):

php /path/to/site/core/components/stats3x/cron.php -v --task=vestnik

If the report did not arrive

First open the State tab: the "Email reports" card shows whether sending is enabled, who the recipients are and when the last report was sent, and the "Cron tasks" table shows the result of the last run of the "Email report via Vestnik" task. Then go by the symptoms:

• "The Vestnik component is not installed" - install Vestnik.
• No "Send report now" button - stats3x.vestnik_recipients is empty or you do not have the stats3x_save permission.
• "Email reports are disabled" in the task result - enable stats3x.vestnik_enabled.
• "The report will be sent after 7:00" or "The report for ... has already been sent" - everything is fine, the task is waiting for its time.
• "Vestnik did not queue any email" - the "Stats3x: email report" rule or its template is disabled, or the rule event key was changed. Enable them in Vestnik on the Rules and Templates tabs.
• Emails stay on the Vestnik Queue tab - the Vestnik cron does not work. Add the job (setup step 3) or click "Process queue".
• Failed status in the Log - the reason is in the Error column. Usually it is the MODX mail settings (SMTP server, port, login, password) or a sender not on the site domain.
• All emails go to one address - the Vestnik debug mode vestnik_debug_mode is on: emails go to vestnik_debug_email.
• Sent in the Log, but no email - check the spam folder, set up SPF and DKIM for the sender domain.
• Zeros in the email - there is no data for the period: check that the Stats3x cron works and the snippet is on the pages.

With the vestnik_debug_mode setting on, Vestnik writes to the MODX error log what it does with each event (how many rules matched, why an email was not queued). Turn it on only while checking: in this mode all emails go to vestnik_debug_email.

For developers: a report from your own code

The email data for any period is prepared by the Stats3x\EmailReport class. For example, send the report for the last month to a separate address from your own snippet or plugin:

$modx->lexicon->load('stats3x:default');
$report = new \Stats3x\EmailReport($modx);
[$from, $to] = \Stats3x\EmailReport::lastPeriod('monthly');
$data = $report->data($from, $to);

$modx->services->get('Vestnik')->trigger(
    'stats3x.report',
    ['email' => 'director@example.com'] + $data,
    'component'
);

For a different kind of email create your own event in Vestnik (for example, my.report.director), a rule for it with the "Explicit address" strategy and your own template, and call trigger() with this key - the placeholders are the same.