---
last_review: ""
last_reviewer: ""
documented_code: [ ]
metadata:
  target_user: "Administrator"
---

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

# Migrate Email Sending from sendmail to SMTP

This guide explains how to migrate server-side scripts from the old sendmail-based email
setup (`caosadvancedtools.serverside.helper.send_mail`) to pylinkahead's native SMTP-based
`send_email`. After the migration, LinkAhead no longer needs access to a `sendmail` binary
or a local mail relay on the host.

## Prerequisites

- You have identified all server-side scripts that currently call
  `helper.send_mail(...)`.
- You have the credentials and hostname for your institution's SMTP server, or have decided
  on an external relay. See
  [Configure Email for Server-Side Scripts](configure_email.md).

## Steps

1. Configure the new `[Email]` section in
   `caosdb-server/scripting/home/pylinkahead.ini` as described in
   [Configure Email for Server-Side Scripts](configure_email.md).

   If your old setup used an external relayhost (configured via `relayhost` in
   `custom/other/main.cf`), you can point `smtp_server` directly at that host with no TLS
   or credentials -- no Postfix intermediary is needed:

   ```ini
   [Email]
   smtp_server=relay.host.example.com
   smtp_port=25
   from_address=LinkAhead <linkahead@example.com>
   ```

2. Update each server-side script that calls `helper.send_mail`. Replace it with
   `send_email` from pylinkahead:

   Old:
   ```python
   from caosadvancedtools.serverside import helper

   helper.send_mail(from_addr="linkahead@example.com", to=recipient,
                    subject=subject, body=message, cc=cc, bcc=bcc)
   ```

   New:
   ```python
   from linkahead.utils.email import send_email

   send_email(message=message, to=recipient, from_address="linkahead@example.com",
              subject=subject, cc=cc, bcc=bcc)
   ```

   The key differences:
   - `body` is renamed to `message` and becomes the first positional argument.
   - `from_addr` is renamed to `from_address`. If you set `from_address` in the
     `[Email]` section of `pylinkahead.ini`, you can omit it from each call entirely.
   - `subject`, `cc`, and `bcc` remain unchanged but are now keyword arguments.
   - `send_mail_bin` has no equivalent and should be dropped.

   Developers can use the [test email setup](/how_to/dev_guides/pylib/test_email.md)
   to verify their changes locally before deploying.

3. Remove the old configuration:

   - In `caosdb-server/scripting/home/pylinkahead.ini`, remove the `sendmail` entry from
     the `[Misc]` section:

     ```ini
     [Misc]
     sendmail=/usr/sbin/sendmail  # remove this line
     ```

   - If you had a relayhost setup and `custom/other/main.cf` is not used for anything
     else, delete it.

4. In your `profile.yml`, set `mail` to `false` and remove the `sendmail` entry (or leave
   it -- it is ignored when `mail` is `false`):

   ```yaml
   mail: false
   # sendmail: /usr/sbin/sendmail  # no longer needed
   ```

5. If the local mail relay (e.g. Postfix) was running solely to support this setup and is
   not used for anything else, you can now decommission it.