Newsletters

Squirro provides supports out of the box for configuring and sending regular newsletters to end users.

Table of Contents

Initial Setup

On a new server some initial configuration needs to be done by the system administrator to enable email sending.

These settings have already been done for you in https://squirro.atlassian.net/wiki/spaces/DOC/pages/2259091732 instances.

  1. The frontend_tld options needs to point to the correct server address, so that newsletter links point to the correct locations. This is set in the https://squirro.atlassian.net/wiki/spaces/DOC/pages/2457272457/digestmailer.ini configuration file - please refer to that documentation for details.

  2. The server needs to be able to send out emails. For this SMTP settings need to be configured. Refer to https://squirro.atlassian.net/wiki/spaces/DOC/pages/348684401/emailsender.ini for details on this.

Enable Newsletter

The email newsletter is enabled on each project.

  1. Navigate to the Setup space, and select the Settings tab.

  2. If not yet enabled, toggle the “Schedule Newsletter” option:

     

  3. Enter the cron-style scheduling expression for when to send the emails.

Cron Expressions

Cron scheduling expressions are a very powerful format for specifying repeating time intervals. It consists of five space-separated expressions for:

  1. Minute

  2. Hour

  3. Day of month

  4. Month

  5. Weekday

Each of those fields can be a complex expression. A few examples:

Description

Cron Expression

Description

Cron Expression

0 8 * * *

Every day at 8am

0 8 * * 1

Every Monday at 8am

0 8-17 * * *

Every hour from 8am to 5pm

0 8 * * 1-5

Every weekday at 8am

0 8,13 * * 1-5

Every weekday at 8am and 1pm

*/5 * * * *

Every 5 minutes

User Opt-out

When newsletters are enabled on a project, all users are automatically signed up for that newsletter.

They can unsubscribe by visiting their user profile:

  1. Use the avatar menu at the top right, and select “My Account”.

     

  2. In the “Newsletter Subscriber” drop-down select Yes or No. This drop-down is only present if newsletters have been enabled on the project.

Edit Template

Newsletter templates are globally configured in the Server space. There navigate to “Emails”, and then edit the “Newsletter” template.

The templates can be edited using a visual editor. But the content can also contain templates, which are rendered as a Jinja2 template.

The following data is fetched for a user:

  • Top 3 items from communities subscribed by the user are fetched as shown below. These items are updated according to the last time a newsletter was sent.

  • The trending communities, i.e. community subscribed by most users and its respective item count is fetched as shown below:

  • Additional data can be fetched by setting “DATA URLs“ in the email template page. See the section Fetching Custom Data below.

Community Subscriptions Needed

The newsletter, including when using the preview function, is only sent when the current user has subscribed to at least one community, and when that community contains data.

See https://squirro.atlassian.net/wiki/spaces/DOC/pages/2266399607/Communities for how to set up and subscribe to communities.

Fetching Custom Data

In the “Data URLs” section, you can specify a number of resources from which to retrieve additional data to be included in the newsletter.

When the newsletter is sent, data is fetched from these URLs and this data is made available to the template.

As an example we use the link at https://jsonplaceholder.typicode.com/todos/1 which contains the data shown below:

1 2 3 4 5 6 { "userId": 1, "id": 1, "title": "delectus aut autem", "completed": false }

Enter the identifier and URL as follows:

This can now be referenced in the template using `digest

In the template, following placeholder can be used to refer your data. Notice that the key here should match the one set for the URL.

1 {{ digest.data.my_endpoint }}

 

This will result in an email with subject: “Newsletter for data example: delectus aut autem“.

These data URLs can also be a Squirro url and can contain user_id and project_id as shown. In such cases, the project_id and user_id is replaced with the specific user to whom the newsletter is sent.

1 my_squirro_endpoint/{{ project_id }}/{{ user_id }}