---
last_review: "2026-04-15"
last_reviewer: "Florian Spreckelsen"
documented_code: [ ]
metadata:
  target_user: "Developer, Administrator"
---

```{tags} howto, developer, administrator, email
```

# Test Email Setup

This guide shows how to test the email functionality of pylinkahead locally using a
throwaway SMTP server.

## Prerequisites

* You need to have pylinkahead installed
* You need docker

## Steps

We run [Mailpit](https://mailpit.axllent.org/) as a local SMTP server which does not actually send the
mails. See the [Mailpit documentation](https://mailpit.axllent.org/docs/) for configuration options.

1. Create a docker compose file:

   ```yaml
   # ./docker-compose.yml
   services:
     mailpit:
       image: axllent/mailpit:v1.29
       command:
         - "--smtp-tls-cert"
         - "sans:localhost"
         - "--smtp-tls-key"
         - "sans:localhost"
       ports:
         - 8025:8025
         - 1025:1025
       environment:
         MP_SMTP_REQUIRE_STARTTLS: true
         MP_SMTP_AUTH_ALLOW_INSECURE: 0
         MP_SMTP_AUTH: "user1:password"
   ```

2. Start the SMTP server:
    ```shell
    docker compose up -d
    ```
3. Configure pylinkahead, add an `[Email]` section to your pylinkahead.ini:

    ```
    # ./pylinkahead.ini
    [Email]
    smtp_server=localhost
    smtp_starttls=yes
    smtp_tls_verify=no
    smtp_port=1025
    smtp_username=user1
    smtp_password=password
    smtp_timeout=1.0
    from_address="Test" <test@example.com>
    bcc_append=logger@example.com
    ```

    `smtp_tls_verify=no` disables certificate verification -- safe here because Mailpit runs
    locally with a self-signed certificate, but never use this in production.
4. Run interactive tests from the python REPL. A successful call returns `None` silently;
   verify delivery in the next step.

   ```python
   >>> from linkahead.utils.email import send_email
   >>> send_email(message="test", subject="subj", to="to@example.com", cc="cc@example.com", bcc="bcc@example.com")
   ```

5. Check that the mail arrived: browse to `http://localhost:8025`.
6. Finally, shut down Mailpit with `docker compose down`. This also deletes all test mails.

If you're interested in how to configure your LinkAhead server so that you can
use `linkahead.utils.email` to send mails, e.g., in your server-side scripts,
please check out [the administration
guide](/how_to/admin_guides/general_functions/configure_email.md).