DOCSEARCHbyAlgolia
Submit Docs

mailrise

repository·main·Indexed 23 days ago

https://github.com/yoryan/mailrise

An SMTP gateway that converts incoming emails into Apprise notifications. It acts as an email relay for legacy or email-only devices (such as IoT devices, surveillance systems, or Linux servers) to send notifications to over 60+ services supported by Apprise, including Discord, Matrix, and Pushover.

Tokens
4.6K
Snippets
8
Records
32
Agent score
78%

What's inside mailrise

  1. What is Mailrise?

    main
    Mailrise is an SMTP gateway that converts incoming emails into Apprise notifications. It acts as an email relay for devices or software that only support SMTP (like Linux servers, IoT devices, or surveillance systems), allowing them to send notifications to over 60+ services supported by Apprise (e.g., Matrix, Nextcloud, Discord, Pushover).

  2. How Mailrise routing and configuration works

    main

    Mailrise uses the recipient address of an incoming email to determine which Apprise configuration to use.

    Routing Logic

    1. Configuration Selection: The username component of the recipient email address corresponds to a configuration name defined in your configs block.
      • Example: If your config has a pushover block, sending an email to pushover@mailrise.xyz will use that configuration.
    2. Notification Types: You can append a .<type> to the username to specify one of the four Apprise notification types (e.g., failure). This can change the icon color in supported services.
      • Example: discord.failure@mailrise.xyz selects the discord config and sets the type to failure.
    3. Attachments: Email attachments are passed through to Apprise if the target notification service supports them.
    # Example minimal configuration
configs:
  pushover:
    urls:
      - pover://[...]

  3. Use Template Strings for Notifications

    main

    You can customize how email content is transformed into notifications using Python template strings. Use the $ prefix to insert variables into title_template and body_template.

    Available variables:

    • subject: The email subject.
    • from: The sender's full address.
    • body: The full contents of the email body.
    • to: The full email address of the selected Apprise configuration.
    • config: The name of the selected Apprise configuration (or the to address if a custom domain is used).
    • type: The Apprise notification class (info, success, warning, or failure).

  4. Set up a local development environment for mailrise

    main

    To contribute to mailrise, follow these steps to prepare your local machine:

    1. Create an isolated virtual environment

    Use virtualenv or conda to avoid conflicts with your system packages.

    Using virtualenv:

    virtualenv <PATH TO VENV>
source <PATH TO VENV>/bin/activate

    Using Miniconda:

    conda create -n mailrise python=3 six virtualenv pytest pytest-cov
conda activate mailrise

    2. Clone and install the package

    Fork the repository on your service (e.g., GitHub), then clone your fork and install the package in editable mode so changes are reflected in your Python REPL.

    git clone git@github.com:YourLogin/mailrise.git
cd mailrise
pip install -U pip setuptools -e .

    3. Install pre-commit hooks

    mailrise uses pre-commit to automatically check code style (using flake8 and black) and other quality metrics.

    pip install pre-commit
pre-commit install
    git clone git@github.com:YourLogin/mailrise.git
cd mailrise
pip install -U pip setuptools -e .

pip install pre-commit
pre-commit install

  5. Compile and preview documentation locally

    main

    The mailrise documentation is built using Sphinx. To compile the documentation locally for testing changes, use tox:

    tox -e docs

    Once compiled, you can preview the documentation in your browser using Python's built-in web server:

    python3 -m http.server --directory 'docs/_build/html'

    Then navigate to http://localhost:8000 in your web browser.

    tox -e docs
python3 -m http.server --directory 'docs/_build/html'

  6. Setup TLS with Traefik (Recommended)

    main

    Instead of managing certificates inside Mailrise, you can run Mailrise in plaintext and use Traefik to handle TLS/ACME (Let's Encrypt). This allows SMTP clients to connect via TLS-on-connect (Port 465).

    Example docker-compose.yml snippet:

    mailrise:
  image: yoryan/mailrise
  container_name: mailrise
  restart: unless-stopped
  volumes:
    - ./mailrise.conf:/etc/mailrise.conf:ro
  labels:
    traefik.tcp.routers.mailrise.rule: "HostSNI(`*`)"
    traefik.tcp.routers.mailrise.tls: "true"
    traefik.tcp.routers.mailrise.tls.certresolver: "letsencrypt"
    traefik.tcp.routers.mailrise.tls.domains[0].main: "my.public.mailrise.domain.com"
    traefik.tcp.routers.mailrise.tls.domains[0].sans: ""
    traefik.tcp.routers.mailrise.entrypoints: "mailsecure"

    And traefik.yml configuration:

    entryPoints:
  mailsecure:
    address: ":465"
    mailrise:
  image: yoryan/mailrise
  container_name: mailrise
  restart: unless-stopped
  volumes:
    - ./mailrise.conf:/etc/mailrise.conf:ro
  labels:
    traefik.tcp.routers.mailrise.rule: "HostSNI(`*`)"
    traefik.tcp.routers.mailrise.tls: "true"
    traefik.tcp.routers.mailrise.tls.certresolver: "letsencrypt"
    traefik.tcp.routers.mailrise.tls.domains[0].main: "my.public.mailrise.domain.com"
    traefik.tcp.routers.mailrise.tls.domains[0].sans: ""
    traefik.tcp.routers.mailrise.entrypoints: "mailsecure"

  7. Install Mailrise via Docker

    main

    You can use the official Docker image from Docker Hub. You must bind mount a configuration file to /etc/mailrise.conf.

    Important: The mount must be a file, not a directory.

    NAS Specific Instructions

    • Unraid: Since Unraid only supports directory passthrough, do not attempt to bind mount the file directly as it may break your system. Instead, override the image's default command to use a volume flag like -v /etc/myconfig/mailrise.conf so you can pass through a directory containing the config.
    • TrueNAS SCALE: Mailrise is designed to run as a non-root container. Ensure the container is running as user 999 and group 999 to avoid permission issues.

  8. Install Mailrise from PyPI

    main

    Mailrise is available on PyPI. The minimum required Python version is 3.8+.

    After installation, you should create a configuration file and run Mailrise as a service. Below is a suggested systemd unit file for running Mailrise as a service:

    [Unit]
Description=Mailrise SMTP notification relay

[Service]
ExecStart=/usr/local/bin/mailrise /etc/mailrise.conf

[Install]
WantedBy=multi-user.target

  9. Workflow for submitting code contributions

    main

    Follow this workflow to ensure your code changes are accepted:

    1. Discuss first: For non-trivial changes, open an issue in the issue tracker to discuss your approach before writing code.
    2. Branching: Never work on the main branch. Create a feature branch:
      git checkout -b my-feature
    3. Implementation:
      • Add docstrings to new functions, modules, and classes (especially public APIs).
      • Add yourself to AUTHORS.rst.
      • Crucial: Add unit tests and documentation for any new features.
    4. Validation:
      • Ensure pre-commit passes all checks.
      • Run tests using tox to ensure no regressions:
        tox
       (Use `tox -av` to see available checks).
    5. Commit and Push:
      git add <MODIFIED FILES>
git commit
git push -u origin my-feature
    6. Submit: Go to your fork's web page and click the button to create a Pull Request.
    git checkout -b my-feature
git add <MODIFIED FILES>
git commit
git push -u origin my-feature

  11. Determine notification type from email address

    main

    The SimpleRouter can automatically determine the Apprise NotifyType (severity) based on the suffix of the recipient's username. If a suffix is detected, the router uses that type; otherwise, it defaults to INFO.

    Supported suffixes are:

    • .info $\rightarrow$ apprise.NotifyType.INFO (Default)
    • .success $\rightarrow$ apprise.NotifyType.SUCCESS
    • .warning $\rightarrow$ apprise.NotifyType.WARNING
    • .failure $\rightarrow$ apprise.NotifyType.FAILURE

    Example: Sending an email to alerts.failure@mailrise.xyz will trigger a notification with the FAILURE severity level.

  12. Extend Mailrise with custom Python code

    main

    Mailrise allows you to plug in custom logic for routing and authentication by importing external Python modules. You can specify a path to a Python file using the import_code key in your configuration.

    The imported module should provide (optionally):

    • router: A custom Router instance.
    • authenticator: A custom AuthenticatorType instance.

    If import_code is provided, Mailrise will attempt to load the module and use its provided components. If they are not present, it falls back to the default simple router and authenticator.