newsletter-to-kindle

newsletter-to-kindle is a NodeJS application to create a service for reading newsletter RSS feed regularly and deliver content to Kindle devices.

Content is delivered using Amazon's Send to Kindle service. See more at https://www.amazon.com/gp/sendtokindle/email.

Motivation

Like most people, I get a lot of newsletters in my email inbox talking about very interesting subjects (and others not so). But as a regular Kindle user, I was unhappy about having to read these newsletters on my cell phone or computer. I missed reading this content on my Kindle device! So I was thinking about creating a project for this purpose, researching how it could work. I saw that most newsletters had RSS feeds to subscribe and there is also Amazon's Send to Kindle service. I developed an initial prototype to send the content of one newsletter to my Kindle device only. And when I was checking the results, little by little, new ideas were emerging and I made more improvements until the project we have today. This api can be used soon by content creators who wish to make their newsletter content available to this audience.

How it works?

Requirements

1. NodeJS;
2. MySQL server;
3. SMTP server and an email address to post and convert articles to Kindle email;
4. Configure Amazon Send to Kindle service to receive messages from this email;

External services

Services that are not mandatory to run in a development environment, but to have the application running with all functionalities, they must be used. The application is ready for the services below, but you can use services from anothers providers (as long as you make adaptations, of course).

1. Loggly;
2. Microsoft Translation API.

Installation

Manual installation

Clone the project and them run to install Node packages.

npm install

You must create a local MySQL database (by the official installer or docker, as you wish).

After that, you must create an .env file, entering the appropriate values for your environment. See .env.example to see all environment variables must be filled. This can help you to create your own .env file.

Now you must run database migrations.

npx sequelize-cli db:migrate

Run seeders to create initial settings. It will create the first user of api, an admin user, which must be created when the application is installed.

npx sequelize-cli db:seed:all

After that, run the following command to start api in development mode.

npm run dev

To run api delivery job of newsletters, run the following command:

npm run jobs

Docker

You can build and run docker image or use docker compose

Build and use image

To build image and create a container, run the following commands:

docker image build -t newsletter-to-kindle .
docker container run -d -p 3001:3001 --name ntk-api newsletter-to-kindle

Docker Compose

Run the following commands:

docker compose up -d

Stop the container:

docker compose stop

To remove container (and related volumes):

docker compose down --volumes 

Usage

You must publish api and start api service.

You must now manipulate the API. We haven't finalized a frontend project yet. See the Postman api documentation in docs/postman for more information.

Now login to the API through the authentication endpoint: Auth -> Login (if you don't have a registered user, you will have to create one or use the default admin user).

Create a new newsletter through the appropriate endpoint: Newsletter -> Create.

Provide to your subscribers with a page where they can subscribe for the service (Subscriptions -> Create), and instructions about how to use Amazon's Send to Kindle service. Providing all the necessary information, especially the email address of the application that will deliver the newsletters. See more at https://www.amazon.com/gp/sendtokindle/email, to help you to create the instructions page.

You can include an acceptance to the terms of use and explain that the user will receive a post to confirm enrollment on their Kindle. All newsletters received will contain links for the user to unsubscribe from the service. Please note that your newsletter subscription and this service are treated as separate mechanisms. But you can subscribe/unsubscribe then from both, as you wish.

You can enable/disable delivery of newsletters and also delete newsletters/subscriptions at any time using the appropriate endpoints.

Avaiable Languages

• Brazilian Portuguese;
• English.

Project Status

🚀 Beta version 🚧

Version

0.11.0: Beta version.

Features

• Read newsletter feed content and post articles to kindle delivery email;

• Registration of multiple feeds;

• Article translations (full or bilingual translation, based on Microsoft Translator API);

• Rest API to manage newsletters, users and subscriptions;

• Log of submitted articles to improve the delivery verification;

• Allow sending article images;

• (optional) The application currently sends 1 file for each article. Perhaps this can be improved in the future.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate.

Frontend Project

It is under development by Samuel Mota . Frontend Project: https://github.com/samuel-mota/newsletter-to-kindle-front

Credits

Diego Queres

License

MIT