Doveseed is a backend service for email subscriptions to RSS feeds.
Doveseed requires a configuration file in JSON format. Take a look at
config.sample.json
. The format is as follows:
db
: JSON file in which Doveseed persists its data.rss
: URL to the RSS feed for which new notifications are to be send.smtp
host
: SMTP host used to send notification emails.port
: SMTP port used to send notification emails (defaul:0
= auto-select).user
: SMTP logon user name.password
: SMTP logon password.ssl_mode
: Activate/deactivate SSL/TLS, valid values"no-ssl"
,"start-tls"
,"tls"
(default"start-tls"
).check_hostname
: Whether to verify the hostname when using TLS (defaulttrue
).
template_vars
: Defines template variables to replace in the email templates.display_name
: Name for the website to use in emails.host
: Hostname of the website.sender
: Email address that is sending the notifications.confirm_url_format
: Template for the URL that is used for confirmation links. The following values will be replaced in it:{host}
with the specified host,{email}
with the email address to confirm,{token}
with the confirmation token,{{
and}}
with{
and}
.
email_templates
: Path to the templates for the emails.confirm_timeout_minutes
: Timeout in minutes during which a subscription needs to be confirmed.
Ensure that the configuration files have appropriate permissions, i.e. only readable by you and Doveseed.
By default the configuration filename is assumed to be config.json
.
Templates for the emails sent out are written in
Jinja.
Look in templates/example
for example email templates.
There is a template for each type of email being sent:
new-post.*
: for notifications about new posts,subscribe.*
: for requesting confirmation to a new subscription,- and
unsubscribe.*
: for requesting confirmation to a cancellation of a subscription.
Each of these templates consists out of three files:
*.subject.txt
: for the subject line of the email,*.txt
: for the plain text version of the email,- and
*.html
: for the HTML version of the email.
The REST service runs as a Python ASGI app. See the FastAPI documentation for deployment options.
To set appropriate CORS headers use the FastAPI CORSMiddleware. Activate it by adding the following lines to the file where you instantiate the app:
from doveseed.app import app from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins=["http://example.com"], allow_methods=["GET", "POST"], allow_headers=["Authorization"], )
You activate ReCaptcha (v2) verification of requests with Doveseed.
First, you need to install the required optional dependencies:
pip install 'doveseed[recaptcha]'
Then, add the follwing lines to the file where you instantiate the app:
from doveseed.app import app from doveseed.recaptcha import ReCaptchaMiddleware app.add_middleware = ReCaptchaMiddleware('^/(un)?subscribe/.*', 'recaptcha.json')
Also, create the recaptcha.json
with the required ReCaptcha configuration:
hostnames
: List of hostnames to accept ReCaptchas from.secret
: The shared key between your site and reCAPTCHA.
Ensure that the configuration files have appropriate permissions, i.e. only readable by you and Doveseed.
Expired pending subscription can be cleaned from the database with:
python -m doveseed.cli clean <path to config file>
Ideally, this command is run once per day as a cron job.
To check for new post and send notification emails run:
python -m doveseed.cli notify <path to config file>
This can either run in a regular interval as a cron job or it can be triggered in some way after new posts have been published.
Run this command once to initialize the database before going live because initially all items in the RSS feed will be considered to be old. (This prevents sending a notification email for all already existing items in the feed.)
To check the service health:
GET /health
Returns a 204 (no content) status if the service is up and running.
To subscribe with an email address:
POST /subscribe/<url encoded email> Content-Type: application/json { captcha: "ReCaptcha returned from Google API" }
This will return a 201 NO CONTENT
and send out the email requesting
confirmation.
To unsubscribe an email address:
POST /unsubscribe/<url encoded email> Content-Type: application/json { captcha: "ReCaptcha returned from Google API" }
This will return a 201 NO CONTENT
and send out the email requesting
confirmation if the email is subscribed.
To confirm a request to subscribe or unsubscribe:
POST /confirm/<url encoded email> Content-Type: application/json Authorization: Bearer <token from confirmation reuest email>
This will return a 201 NO CONTENT
on success,
and 401 UNAUTHORIZED
if the token or email is invalid.