diff --git a/API.md b/API.md index 9048d933..557bbcd5 100644 --- a/API.md +++ b/API.md @@ -32,6 +32,21 @@ General optional parameters: ## API methods +### add_newsletter_config +Add a new notification agent. + +``` +Required parameters: + agent_id (int): The newsletter type to add + +Optional parameters: + None + +Returns: + None +``` + + ### add_notifier_config Add a new notification agent. @@ -98,11 +113,13 @@ Delete the images uploaded to image hosting services. ``` Required parameters: + None + +Optional parameters: rating_key (int): 1234 (Note: Must be the movie, show, season, artist, or album rating key) -Optional parameters: - service (str): imgur or cloudinary - (Note: Defaults to service in Image Hosting setting) + service (str): 'imgur' or 'cloudinary' + delete_all (bool): 'true' to delete all images form the service Returns: json: @@ -192,6 +209,36 @@ Returns: ``` +### delete_newsletter +Remove a newsletter from the database. + +``` +Required parameters: + newsletter_id (int): The newsletter to delete + +Optional parameters: + None + +Returns: + None +``` + + +### delete_newsletter_log +Delete the Tautulli newsletter logs. + +``` +Required paramters: + None + +Optional parameters: + None + +Returns: + None +``` + + ### delete_notification_log Delete the Tautulli notification logs. @@ -1167,6 +1214,109 @@ Returns: ``` +### get_newsletter_config +Get the configuration for an existing notification agent. + +``` +Required parameters: + newsletter_id (int): The newsletter config to retrieve + +Optional parameters: + None + +Returns: + json: + {"id": 1, + "agent_id": 0, + "agent_name": "recently_added", + "agent_label": "Recently Added", + "friendly_name": "", + "id_name": "", + "cron": "0 0 * * 1", + "active": 1, + "subject": "Recently Added to {server_name}! ({end_date})", + "body": "View the newsletter here: {newsletter_url}", + "message": "", + "config": {"custom_cron": 0, + "filename": "newsletter_{newsletter_uuid}.html", + "formatted": 1, + "incl_libraries": ["1", "2"], + "notifier_id": 1, + "save_only": 0, + "time_frame": 7, + "time_frame_units": "days" + }, + "email_config": {...}, + "config_options": [{...}, ...], + "email_config_options": [{...}, ...] + } +``` + + +### get_newsletter_log +Get the data on the Tautulli newsletter logs table. + +``` +Required parameters: + None + +Optional parameters: + order_column (str): "timestamp", "newsletter_id", "agent_name", "notify_action", + "subject_text", "start_date", "end_date", "uuid" + order_dir (str): "desc" or "asc" + start (int): Row to start from, 0 + length (int): Number of items to return, 25 + search (str): A string to search for, "Telegram" + +Returns: + json: + {"draw": 1, + "recordsTotal": 1039, + "recordsFiltered": 163, + "data": + [{"agent_id": 0, + "agent_name": "recently_added", + "end_date": "2018-03-18", + "id": 7, + "newsletter_id": 1, + "notify_action": "on_cron", + "start_date": "2018-03-05", + "subject_text": "Recently Added to Plex (Winterfell-Server)! (2018-03-18)", + "success": 1, + "timestamp": 1462253821, + "uuid": "7fe4g65i" + }, + {...}, + {...} + ] + } +``` + + +### get_newsletters +Get a list of configured newsletters. + +``` +Required parameters: + None + +Optional parameters: + None + +Returns: + json: + [{"id": 1, + "agent_id": 0, + "agent_name": "recently_added", + "agent_label": "Recently Added", + "friendly_name": "", + "cron": "0 0 * * 1", + "active": 1 + } + ] +``` + + ### get_notification_log Get the data on the Tautulli notification logs table. @@ -2277,6 +2427,23 @@ Returns: ``` +### notify_newsletter +Send a newsletter using Tautulli. + +``` +Required parameters: + newsletter_id (int): The ID number of the newsletter agent + +Optional parameters: + subject (str): The subject of the newsletter + body (str): The body of the newsletter + message (str): The message of the newsletter + +Returns: + None +``` + + ### notify_recently_added Send a recently added notification using Tautulli. @@ -2392,6 +2559,22 @@ Returns: ``` +### set_newsletter_config +Configure an exisitng newsletter agent. + +``` +Required parameters: + newsletter_id (int): The newsletter config to update + agent_id (int): The newsletter type of the newsletter + +Optional parameters: + Pass all the config options for the agent with the 'newsletter_config_' and 'newsletter_email_' prefix. + +Returns: + None +``` + + ### set_notifier_config Configure an exisitng notificaiton agent. diff --git a/plexpy/api2.py b/plexpy/api2.py index 681f5469..76098f29 100644 --- a/plexpy/api2.py +++ b/plexpy/api2.py @@ -37,6 +37,8 @@ import logger import mobile_app import notification_handler import notifiers +import newsletter_handler +import newsletters import users @@ -443,6 +445,51 @@ class API2: return + def notify_newsletter(self, newsletter_id='', subject='', body='', message='', **kwargs): + """ Send a newsletter using Tautulli. + + ``` + Required parameters: + newsletter_id (int): The ID number of the newsletter agent + + Optional parameters: + subject (str): The subject of the newsletter + body (str): The body of the newsletter + message (str): The message of the newsletter + + Returns: + None + ``` + """ + if not newsletter_id: + self._api_msg = 'Newsletter failed: no newsletter id provided.' + self._api_result_type = 'error' + return + + newsletter = newsletters.get_newsletter_config(newsletter_id=newsletter_id) + + if not newsletter: + self._api_msg = 'Newsletter failed: invalid newsletter_id provided %s.' % newsletter_id + self._api_result_type = 'error' + return + + logger.api_debug(u'Tautulli APIv2 :: Sending newsletter.') + success = newsletter_handler.notify(newsletter_id=newsletter_id, + notify_action='api', + subject=subject, + body=body, + message=message, + **kwargs) + + if success: + self._api_msg = 'Newsletter sent.' + self._api_result_type = 'success' + else: + self._api_msg = 'Newsletter failed.' + self._api_result_type = 'error' + + return + def _api_make_md(self): """ Tries to make a API.md to simplify the api docs. """ diff --git a/plexpy/webserve.py b/plexpy/webserve.py index ae902955..4ddc7b42 100644 --- a/plexpy/webserve.py +++ b/plexpy/webserve.py @@ -5552,7 +5552,7 @@ class WebInterface(object): Returns: json: [{"id": 1, - "agent_id": 13, + "agent_id": 0, "agent_name": "recently_added", "agent_label": "Recently Added", "friendly_name": "", @@ -5612,15 +5612,24 @@ class WebInterface(object): Returns: json: {"id": 1, - "agent_id": 13, + "agent_id": 0, "agent_name": "recently_added", "agent_label": "Recently Added", "friendly_name": "", + "id_name": "", "cron": "0 0 * * 1", - "active": 1 - "config": {"time_frame": 7, - "time_frame_units": "days", - "incl_libraries": [1, 2] + "active": 1, + "subject": "Recently Added to {server_name}! ({end_date})", + "body": "View the newsletter here: {newsletter_url}", + "message": "", + "config": {"custom_cron": 0, + "filename": "newsletter_{newsletter_uuid}.html", + "formatted": 1, + "incl_libraries": ["1", "2"], + "notifier_id": 1, + "save_only": 0, + "time_frame": 7, + "time_frame_units": "days" }, "email_config": {...}, "config_options": [{...}, ...], @@ -5667,19 +5676,15 @@ class WebInterface(object): @requireAuth(member_of("admin")) @addtoapi() def set_newsletter_config(self, newsletter_id=None, agent_id=None, **kwargs): - """ Configure an exisitng notificaiton agent. + """ Configure an exisitng newsletter agent. ``` Required parameters: - newsletter_id (int): The newsletter config to update - agent_id (int): The newsletter type of the newsletter + newsletter_id (int): The newsletter config to update + agent_id (int): The newsletter type of the newsletter Optional parameters: - Pass all the config options for the agent with the agent prefix: - e.g. For Recently Added: recently_added_last_days - recently_added_incl_movies - recently_added_incl_shows - recently_added_incl_artists + Pass all the config options for the agent with the 'newsletter_config_' and 'newsletter_email_' prefix. Returns: None @@ -5697,7 +5702,6 @@ class WebInterface(object): @cherrypy.expose @cherrypy.tools.json_out() @requireAuth(member_of("admin")) - @addtoapi("notify_newsletter") def send_newsletter(self, newsletter_id=None, subject='', body='', message='', notify_action='', **kwargs): """ Send a newsletter using Tautulli.