Sorting Tautulli Newsletter Items with a Custom Template

If you’ve been running a Plex server for more than a couple weeks, odds are you’re also using Tautulli for server monitoring and notifications. With the recent release of Tautulli’s email newsletters feature, it’s never been easier to send your users a beautifully formatted email each week with all the exciting new content that’s been added. That said, the default options for customizing newsletters in the Tautulli UI are pretty limited, but never fear- we can fix that with a custom newsletter template and some simple Python code!



Creating a Custom Newsletter Template

The Tautulli Wiki has some basic guidelines for creating and using a custom template, but we’ll go into a little more detail here.

First, some background info. Tautulli uses a template file called recently_added.html to generate the Recently Added newsletter, and it’s written in a language called Mako, which is basically a mix of HTML/CSS and Python. The Python code is used to pull in and modify dynamic data (such as your lists of recently added content) and the HTML/CSS formats and presents it in a nice way, but we’ll get more into this later.

We’ll need to create a directory for custom newsletter templates, and then copy the default template Tautulli uses to generate a newsletter so we can customize it safely.

On the server where you’re running Tautulli, navigate to the Tautulli base directory. For me on Ubuntu 16.04, that’s located at if you’re using a different OS, check the wiki for this location): /opt/Tautulli (

cd /opt/Tautulli

We’ll create a new directory to store our custom newsletter template. Note that for most OSes, you’ll need elevated permissions to do this since the base directory is owned by the Tautulli user. Long story short- use ‘sudo’ here:

sudo mkdir custom-newsletters

Next we’ll copy the default “Recently Added” newsletter template to our new folder. We need to keep the filename exactly the same:

sudo cp data/interfaces/newsletters/recently_added.html /custom-newsletters/recently_added.html

Now that we have a duplicate copy of the default template, we can start editing it!

Sorting Movies by Rating

By default, the Recently Added newsletter just displays your recently added shows, movies, etc in the order they were added, most recently first. Personally, I find it kind of annoying that an awesome movie like Black Panther might get buried at the bottom of the list if a bunch of other bad movies (eg, Battle: Los Angeles) get added afterwards.

Since I want my best content to appear at the top where it’s most likely to be seen, for this example I’m going to be changing the template so that movies are sorted by rating, with the highest rated movies appearing at the top! We can do this by adding a couple lines of Python code to the template to sort the ‘movies’ object that’s grabbed by Tautulli.

First, open your new custom newsletter template in your text editor of choice. I’m going to be using Nano:

sudo nano custom-newsletters/recently_added.html

Next, find the following line

% if recently_added.get('movie'):

and just below it, insert the following code exactly (since this is Python code, the spaces and indentations are important, you want this to be indented one level below that line):

<% def getSortRating(obj) : return obj['rating'] recently_added['movie'].sort(key=getSortRating, reverse=True) %>

As a quick explanation for what we’re doing here, in Mako, we can enclose arbitrary Python code in <% %> tags. The code itself is defining a simple function to sort the ‘movies’ object that is returned when Tautulli generates the newsletter by the ‘rating’ field for each movie. The reverse=True argument makes this a descending sort (by default, it’d be sorted lowest to highest, which is the opposite of what we want)

If you did it correctly, this area of code in the template should now look like something like this:

% if recently_added.get('movie'): <% def getSortRating(obj) : return obj['rating'] recently_added['movie'].sort(key=getSortRating, reverse=True) %> <tr> <td class="wrapper" style="font-family: 'Open Sans', Helvetica, Arial, sans-serif;font-size: 14px;vertical-align: top;box-sizing: border-box;padding: 5px;overflow: auto;">

Save and close your template file

Configure Tautulli to use your custom newsletter template

Now that we’ve created a custom newsletter template, we need to configure Tautulli to use it instead of the default template.

First let’s make sure we have the proper permissions set on our custom template directory and the template itself. If you’re using Windows this might not be necessary, but for Linux, MacOS, FreeBSD, etc we’ll need to change ownership of the custom-newsletters directory and all files within it to the tautulli user and nogroup group:

cd /opt/Tautulli sudo chown -R tautulli:nogroup custom-newsletters

Next, log in to Tatulli, hover over the gear icon at the top right and select “Settings”, and then navigate to “Notifications & Newsletters”

Make sure advanced settings are displayed by clicking the “Show Advanced” button in the top bar

Scroll down to the “Newsletters” section, and find the text box for “Custom Newsletter Templates Folder”. Input the directory you created:

/opt/Tautulli/custom-newsletters

That’s it! Now just create and preview or send a newsletter like usual, and you’ll see that the movies listed are sorted in descending order by rating.

Sorting by other fields, or for other types of content

The same concept above can be applied to other areas of the newsletters as well- for example, to sort shows or music by rating. There are also variety of other fields like ‘year’, ‘genres’, ‘audience_rating’, etc to play with. For your convenience, here’s the movie object Tautulli uses in these newsletters (in this case, for Flash Gordon):

{'rating': u'8.2', 'labels': [], 'parent_rating_key': '', 'parent_title': '', 'guid': '', 'rating_key': u'5877', 'thumb': u'/library/metadata/5877/thumb/1530062411', 'title': u'Flash Gordon', 'tagline': u"He'll save every one of us!", 'last_viewed_at': '', 'user_rating': '', 'collections': [], 'media_type': u'movie', 'grandparent_rating_key': '', 'sort_title': '', 'audience_rating': u'6.9', 'full_title': u'Flash Gordon', 'thumb_hash': '124920c1f5ee72583b97a6eeb31a3a789a639095f4145cac88b08caecaa82aa1', 'banner': '', 'original_title': '', 'added_at': u'1530023846', 'summary': u'A football player and his friends travel to the planet Mongo and find themselves fighting the tyrant, Ming the Merciless, to save Earth.', 'grandparent_title': '', 'parent_media_index': '', 'library_name': u'Movies', 'art': u'/library/metadata/5877/art/1530062411', 'updated_at': u'1530062411', 'year': u'1980', 'duration': u'6687917', 'genres': [u'Action', u'Adventure'], 'art_url': '', 'writers': [u'Lorenzo Semple Jr.'], 'actors': [u'Sam Jones', u'Melody Anderson', u'Max von Sydow'], 'child_count': '', 'poster_url': '', 'section_id': u'1', 'art_hash': '1955392a37dfa8347a387e75f4caeb68c26f94aba68a43b27853646ec84ba65e', 'studio': u'Dino De Laurentiis Company', 'thumb_url': '', 'media_index': '', 'originally_available_at': u'1980-09-01', 'content_rating': u'PG', 'directors': [u'Mike Hodges'], 'parent_thumb': '', 'grandparent_thumb': ''}

Hope this is helpful to someone- if you liked this or have questions, leave me a comment below!