Newsletters

Newsletters#

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

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 Squirro Self-Service instances.

  1. The frontend_tld option must point to the correct server address so that newsletter links point to the correct locations. This is set in the digestmailer.ini configuration file. 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 emailsender.ini for details on this.

Enable Newsletter#

The email newsletter is enabled on each project.

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

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

    image1

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

    image2

Cron Expressions#

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

  1. Minute

  2. Hour

  3. Day of month

  4. Month

  5. Weekday

Each of those fields can be a complex expression.

Warning

For a newsletter to send, new items must have been added since the previous newsletter was sent. If no new items have been added, no newsletter will be sent, regardless of how the CRON is configured.

The following are example scheduling configurations:

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.

    image3

  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.

image4

Edit Template#

Newsletter templates are globally configured in the Server space. From 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 three 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.

image5

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

image6

  • Additional data can be fetched by setting DATA URLs in the email template page.

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. Note that only community items with a recent creation date will be included in the newsletter. If the Creation Date (created_at) field was mapped in the data source of the community items, and the values of the source field are in the past, then those community items will never be included in the newsletter.

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

image7

As an example, consider the link https://jsonplaceholder.typicode.com/todos/1 which contains the data shown below:

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

Enter the identifier and URL as follows:

image8

This can now be referenced in the template using `digest`

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

{{ digest.data.my_endpoint }}

image9

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.

my_squirro_endpoint/{{ project_id }}/{{ user_id }}
Contents