# checker-happydeliver

happyDomain checker that drives a [happyDeliver](https://git.nemunai.re/happyDomain/happyDeliver)
instance to assess outbound email deliverability for a domain.

The checker:

1. Allocates a fresh recipient address on a happyDeliver instance
   (`POST /api/test`).
2. Sends a real test message **from the tested domain** to that address,
   using SMTP credentials supplied by the user.
3. Polls happyDeliver until the message is analysed.
4. Stores happyDeliver's report verbatim as the observation, exposes
   per-section scores as metrics, and emits one rule per section
   (DNS, authentication, spam, blacklist, header, content, plus overall)
   that fires CRIT when the score drops under a user-configured minimum.

## Options

### Admin

| Id                   | Type   | Description |
|----------------------|--------|-------------|
| `happydeliver_url`   | string | Default base URL of the happyDeliver API. |
| `happydeliver_token` | secret | Default bearer token for the happyDeliver API. |

### User / per-domain

| Id                   | Type   | Default     | Description |
|----------------------|--------|-------------|-------------|
| `happydeliver_url`   | string | (admin)     | Override the happyDeliver URL. |
| `happydeliver_token` | secret | (admin)     | Override the happyDeliver token. |
| `smtp_host`          | string | (none)           | Submission server. **Required.** |
| `smtp_port`          | number | `587`       | Submission port. |
| `smtp_username`      | string | (none)           | SMTP username (omit for anonymous submission). |
| `smtp_password`      | secret | (none)           | SMTP password. |
| `smtp_tls`           | choice | `starttls`  | `starttls`, `tls`, or `none`. |
| `from_address`       | string | (none)           | From address. **Required.** |
| `subject_override`   | string | (default)   | Override the test subject. |
| `body_text_override` | text   | (default)   | Override the plain-text body. |
| `body_html_override` | text   | (default)   | Override the HTML body. |
| `wait_timeout`       | number | `900`       | Seconds to wait for analysis. |
| `poll_interval`      | number | `5`         | Seconds between polls (clamped to [2, 60]). |
| `min_score_<section>`| number | per-section | Minimum acceptable score for each section. |

### Per-rule minimum scores

Defaults: `overall=70`, `dns=70`, `authentication=80`, `spam=70`,
`blacklist=90`, `header=70`, `content=60`. Each can be customised through
the rule options shown in the happyDomain UI.

## Rules

| Code                                  | Description                                                                                       | Severity |
|---------------------------------------|---------------------------------------------------------------------------------------------------|----------|
| `happydeliver.score.overall`          | Verifies happyDeliver's Overall score is above the configured minimum.                            | CRITICAL |
| `happydeliver.score.dns`              | Verifies happyDeliver's DNS score is above the configured minimum.                                | CRITICAL |
| `happydeliver.score.authentication`   | Verifies happyDeliver's Authentication (SPF/DKIM/DMARC) score is above the configured minimum.    | CRITICAL |
| `happydeliver.score.spam`             | Verifies happyDeliver's Spam filters score is above the configured minimum.                       | CRITICAL |
| `happydeliver.score.blacklist`        | Verifies happyDeliver's Blacklists score is above the configured minimum.                         | CRITICAL |
| `happydeliver.score.header`           | Verifies happyDeliver's Headers score is above the configured minimum.                            | CRITICAL |
| `happydeliver.score.content`          | Verifies happyDeliver's Content score is above the configured minimum.                            | CRITICAL |
| `happydeliver.lifecycle`              | Reports happyDeliver lifecycle errors (allocation, send, timeout, fetch).                         | CRITICAL |

## Metrics

One `happydeliver_score` metric per section, labelled with `section=<name>`
(values: `overall`, `dns`, `authentication`, `spam`, `blacklist`, `header`,
`content`).

## Build

```sh
make            # standalone binary (HTTP server on :8080)
make plugin     # plugin.so loadable by happyDomain
make docker     # container image
```