Skip to content

DOCS.md

Latest commit

 

History

History
214 lines (149 loc) · 7.44 KB

DOCS.md

File metadata and controls

214 lines (149 loc) · 7.44 KB

Home Assistant Add-on: ProtonMail Bridge addon

Supports amd64 Architecture Supports armv7 Architecture

License

ProtonMail does not provide any SMTP server to integrate with the notification system of Home Assistant. Instead they provide a tool called the ProtonMail Bridge.

This bridge should be installed locally and act as a local SMTP server on which we should connect Home Assistant to send notifications.

This bridge is responsible to encrypt emails before sending them to the ProtonMail server.

Installation

You can install this Home Assistant add-on using my add-on repository following these Home Assistant Add-on Instructions.

Configuration

Note: Remember to restart the add-on when the configuration is changed.

Example add-on configuration when directly editing yaml:

username: <my_proton_mail_username>
password: <my_proton_mail_password>
two_factor_code: ""

Note: This is just an example, don't copy and paste it! Create your own!

Option: username

Enter you ProtonMail username in this field.

Option: password

Enter you ProtonMail password in this field.

A security check is made on the password when the addon is starting. The check is searching the password i the HaveIBeenPwned database. If the password is considered unsafe, a warning is displayed in the logs.

Option: two_factor_code

Use it only if enabled on your ProtonMail account.

The management of the 2nd factor code (TOTP) is really simple and can lead to failed authentication. Each code has a lifespan of 30 seconds. Thus the time when entering the code in the configuration, and the time when the addon is started should be has short as possible.

Configuring Home Assistant to send notification using ProtonMail Bridge

Add this in your configuration.yaml file.

notify:
  - name: ProtonMail
    platform: smtp
    sender: <your_protonmail_email_address>
    recipient: email_address_of_recipient
    server: 22fd13a0-pmb
    port: 25
    encryption: none
    username: <your_protonmail_bridge_username>
    password: <generated_protonmail_bridge_password>

Option: username and password

The username is one of your mail address. The one to use is visible in the logs of this addon in the supervisor.

You must use the password generated by the ProtonMail Bridge, not your ProtonMail password. To see this password, check the logs of the addon in the supervisor.

Option: server

Should be always set to 22fd13a0-pmb

Option: sender

Use one of your ProtonMail address to send the notification.

Other options

All other options are explained in the documentation of the SMTP integration.

Known issues and limitations

Changelog & Releases

Releases are based on Semantic Versioning, and use the format of MAJOR.MINOR.PATCH. In a nutshell, the version will be incremented based on the following:

  • MAJOR: Incompatible or major changes.
  • MINOR: Backwards-compatible new features and enhancements.
  • PATCH: Backwards-compatible bugfixes and package updates.

The changelog is available in the file CHANGELOG.md

Support

Got questions?

You can open an issue here GitHub.

You can also ask for help in the dedicated forum topic https://community.home-assistant.io/t/new-addon-protonmail-bridge/277584

Error messages explained

The logs can show some errors. The common errors are explained here:

  • Bad 2FA code Your 2nd factor code is wrong. Fix the two_factor_code in the configuration and restart the addon.
  • Bad username or password The authentication has failed. Fix the username or the password in the configuration and restart the addon.
  • Cannot connect - Please check errors above Some errors occurred when starting the addon. The real error should be displayed in the logs above this line.

Authors & contributors

The original setup of this repository is by Florian Boulay.

It is based on the work of Xiaonan Shen who inspired this repository for the build

Roadmap

Here are some ideas to improve this addon:

  • Use a web interface to enter the 2nd factor code
  • Run the ProtonMail bridge in the background using Systemd (using this tutorial for example https://gist.github.com/ibaiul/60d603845df931483a05d96c5b433981) or S6 overlay Done in version 1.3.0 using S6 overlay
  • Create a change log using GitHub's releases functionality.
  • Exposes services to be able to interact with ProtonMail Bridge within Home Assistant
  • Test this addon on other architectures Done for amd64 in version 1.2.0
  • Check if the ProtonMail password is in the have i been pwned database Done in version 1.2.0
  • Create an automated build to publish all images on Docker Hub when a new release is created Done in version 1.2.0

Testing on you local machine

→ Build the image in the ha-protonmail-bridge directory

docker build --build-arg BUILD_FROM="homeassistant/amd64-base:latest" -t local/my-test-addon .

→ Run built image

docker run --rm -v /tmp/my_test_data:/data -p 25:2525 local/my-test-addon

Inside the directory my_test_data, create a file called options.json with the correct configuration for the addon.

→ Start a shell in the image to debug

docker run --rm -v /tmp/my_test_data:/data -p 25:2525  -ti --entrypoint bash local/my-test-addon

License

MIT License

Copyright (c) 2021 Florian Boulay

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.