smtp2shoutrrr/README.md

# smtp2Shoutrrr

A simple SMTP server that forwards incoming emails to a [Shoutrrr supported service](https://containrrr.dev/shoutrrr/).

## Installing

First generate a new configuration file following this example:

```toml
# config.toml
# Port the SMTP server will listen on
Port = 11025

# Credentials for the SMTP server (required — the server refuses to start without them)
Username = "user"
Password = "nometokens"

# Configure recipients to forward emails to

# Multiple Targets (Recommended)
# Use the Targets array to send notifications to multiple services
[[Recipients]]
# Email addresses to forward emails from
Addresses = ["user@example.com"]
# Shoutrrr services to forward emails to
# See shoutrrr documentation: https://containrrr.dev/shoutrrr/
Targets = [
    "ntfy://ntfy.sh/my-ntfy-topic?tags=email",
    "discord://token@id",
    "slack://token@channel"
]
# Optional: how an HTML message body should reach these targets.
#   "raw"      forward the message unchanged (default)
#   "markdown" render an HTML body as Markdown
# See "Converting HTML messages" below.
# Format = "markdown"

# Single Target (Deprecated)
# The Target field is still supported for backward compatibility
[[Recipients]]
Addresses = ["legacy@example.com"]
Target = "ntfy://ntfy.sh/legacy-topic?tags=thing"  # Will show deprecation warning

# Note: Repeat [[Recipients]] as needed

# Optional: Configure a catch-all recipient for unmatched email addresses
[CatchAll]
# Shoutrrr services to forward unmatched emails to
Targets = ["ntfy://ntfy.sh/catch-all-topic?tags=unmatched"]
# Format applies to the catch-all as well
# Format = "markdown"
```

The server refuses to start if the configuration cannot forward anything — no
recipients and no catch-all, a recipient without addresses or usable targets, or
a mistyped table name such as `[[Recipient]]`, which TOML would otherwise accept
silently, or a `Format` that names none of the supported conversions. It also
refuses to start without a `Username` and a `Password`: these used to fall back
to `username`/`password`, which left the authentication gate open to the most
obvious guess there is.

Clients must authenticate with the configured `Username` and `Password` before
starting a mail transaction; an unauthenticated client is refused rather than
relayed. A client that used to send without issuing `AUTH` has to be configured
with the credentials above.

The reply the sending client gets reflects what happened to the notification:
`250` once at least one target has accepted it, `451` when none did so the
sender retries, and `550` for a message that cannot be parsed at all — a
malformed `Content-Type`, for instance — which no retry could fix. A partial
failure is logged but still accepted, since a retry would redeliver to every
target and duplicate the notification on the ones that already have it.

### From releases

- Grab the latest release from the [releases page](https://git.nakama.town/fmartingr/smtp2shoutrrr/releases)
- Put the configuration file in the same directory as the binary
- Run the binary for your appropriate platform

### From source (development)

- Clone [this repository](https://git.nakama.town/fmartingr/smtp2shoutrrr)
- Put the configuration file in the repository folder
- Run `make quick-run`

### Using docker

- Create a `config.toml` file as described above
- Run the docker image mounting the `Config.toml` file as `/config.toml` and exposing the configured port:

```bash
docker run -v /path/to/config.toml:/config.toml \
    -p 11025:11025 \
    git.nakama.town/fmartingr/smtp2shoutrrr:latest
```

## Converting HTML messages

Plenty of mail carries nothing but HTML, and plenty of notification services
render none of it — a Mattermost direct message shows the markup verbatim.
Setting `Format` on a recipient (or on `[CatchAll]`) rewrites an HTML body
before it is forwarded:

| `Format`   | Effect                                              |
| ---------- | --------------------------------------------------- |
| `raw`      | Forward the body as the message wrote it. (default) |
| `markdown` | Render an HTML body as Markdown.                    |

There is deliberately no plain-text format beside it. Markdown reads as plain
text wherever nothing renders it — that is rather the point of Markdown — so a
second conversion would only be a worse copy of this one.

The value is not case sensitive, and an unrecognised one is refused when the
server starts rather than silently forwarding raw HTML.

Only an HTML body is ever rewritten. A message that arrives as plain text is
what the sender chose to write and is forwarded untouched whatever `Format`
says. Which part of a multipart message that is follows RFC 2046: the parts of
a `multipart/alternative` are the same content in several forms, so the
`text/plain` one is preferred where it is not empty; the parts of any other
multipart are cumulative, so the first one carrying a body is the message and
the footers, signatures and attachments after it are not.

The Markdown itself is produced by
[html-to-markdown](https://github.com/JohannesKaufmann/html-to-markdown), which
knows CommonMark — escaping, delimiter runs, fencing a code block past the
backticks inside it. What it does not know is mail, because it is written for
documents. Before the conversion runs, the parsed message is stripped down to
what a notification should carry:

- Hidden elements go. A template opens with a preheader written for the inbox
  list, which reads as noise anywhere else.
- Images without alt text go, which removes tracking pixels, spacers and
  sliced-up banners. An inline `cid:` attachment leaves its alt text behind as
  ordinary words.
- Destinations a reader cannot open — `#anchors`, `javascript:`, `cid:` — are
  dropped and the text of the link is kept. Tabs and line breaks are removed
  from the rest, since a line break inside an `href` is invisible in the
  document and a fabricated line in the message.
- Table rows become lines and their cells stay apart, since mail lays itself
  out in tables far more often than it tabulates anything.
- Quoting and list nesting is flattened past six levels. A line prefix is
  re-emitted on every line of every level it nests, so depth multiplies against
  line count: a message at the 1 MB limit nested 250 quotes deep otherwise
  renders to 131 MB and takes minutes of CPU.

If a body is too deeply nested for the HTML parser, or renders to nothing at
all because it was images and tracking pixels, it is forwarded unchanged and a
warning is logged: reformatting is a courtesy to the target, not a condition of
delivery. Output past 64 KiB is cut short with a `…`, which no chat target
would have displayed anyway.

Bodies are decoded before they are rendered, so `quoted-printable` and `base64`
transfer encodings and non-UTF-8 character sets (`iso-8859-1`, `windows-1252`,
…) reach the target as readable text in both formats, `raw` included — which is
the one way `raw` is not quite the bytes that arrived.

## Development

Run the server with:

```
make quick-run
```

Send a test email with:

> This will read the `config.toml` in the current directory to set the appropriate SMTP client configuration.

```
go run ./cmd/sendmail/.
```