# Quick start

SendScore checks one received email, a newsletter issue, and returns a verdict with a status for every check, the evidence behind it, and who fixes each problem. The checks are rules, so the same message with the same DNS always gets the same verdict.

There are three ways to use it.

- **Run the CLI on a saved email.** It needs no server. See [Start with the CLI](#start-with-the-cli).
- **Send a test to your own server.** The app gives you an address, and you send a preview to it before you schedule. See [How a check works in the app](#how-a-check-works-in-the-app).
- **Let it watch every issue.** The app subscribes to your newsletter, checks each issue, and alerts you when one gets worse or doesn't arrive. See [Monitoring a newsletter](#monitoring-a-newsletter).

SendScore is open source. The engine and CLI ([sendscore/sendscore](https://github.com/sendscore/sendscore)) are MIT, and the app that receives mail and serves reports ([sendscore/sendscore-app](https://github.com/sendscore/sendscore-app)) is AGPL-3.0. There is no hosted version, and sendscore.ai is only this site. If you would use a hosted version, [say so on this issue](https://github.com/sendscore/sendscore/issues/1).

## Start with the CLI

The CLI reads a saved `.eml` file and prints a verdict. It needs no account and no server, and it works in CI.

```bash
go install github.com/sendscore/sendscore@latest
sendscore check issue.eml
sendscore check --json issue.eml
```

See [the CLI](https://sendscore.ai/docs/cli/) for saving an issue from your mail client, giving it the delivery details, and comparing two issues.

## Run the app for more

[The app](https://sendscore.ai/docs/self-hosting/) runs on your own server. It gives out test addresses, receives the mail, and serves reports, through [MCP tools](https://sendscore.ai/docs/mcp/) and [an API](https://sendscore.ai/docs/api/), and it [monitors](https://sendscore.ai/docs/monitoring/) every issue you send. It needs a server that can receive mail on port 25 and a domain whose MX record points at it.

## How a check works in the app

1. Ask your app for a test address.
2. Send a preview of the issue to it from Kit, Beehiiv, or whatever platform you use.
3. Wait for the message to arrive.
4. Read the verdict. If `ready_to_send` is `true`, schedule the send. If not, `top_fixes` says what to change first.

With the API, that is two requests around the send. Each one carries an API token, which you create on your app's Account page. See [the API](https://sendscore.ai/docs/api/#authentication). In these docs, `https://sendscore.example.com` stands for your app's address.

```bash
export SENDSCORE_TOKEN=ss_live_...
curl -s -X POST -H "Authorization: Bearer $SENDSCORE_TOKEN" \
  https://sendscore.example.com/api/v1/test-addresses
# send the preview to the address it returns, then:
curl -s -H "Authorization: Bearer $SENDSCORE_TOKEN" \
  "https://sendscore.example.com/api/v1/test-addresses/<token>/wait?timeout=50"
```

The app receives the message itself, over SMTP, rather than through a forwarding service. That matters because a forwarder can rewrite headers and hide the sending server, and the checks need to see exactly what your platform delivered.

## From an agent

An agent does the four steps with four MCP tools, `get_test_address`, `wait_for_message`, `get_report`, and `compare_to_previous`. In claude.ai or another MCP client, add your app's `/api/mcp` address as a custom connector, sign in with your email address, and press Allow. In Claude Code, add it and run `/mcp` to sign in:

```bash
claude mcp add --transport http sendscore https://sendscore.example.com/api/mcp
```

Or run the local server, which needs your app's address and an API token, with `claude mcp add sendscore --env SENDSCORE_URL=https://sendscore.example.com --env SENDSCORE_TOKEN=ss_live_... -- sendscore mcp`. Both are in [MCP setup](https://sendscore.ai/docs/mcp/).

## Monitoring a newsletter

In the app, each newsletter you add gets its own address. Subscribe that address to the newsletter like any other reader, and every real issue is checked when it arrives.

- **Alerts** come by email when an issue is worse than the one before it, for example when DKIM passed last week and fails today, and when two issues arrive for one send.
- **The heartbeat** knows when an issue normally goes out, in your time zone, with a grace period. If no issue has reached the monitoring address by the end of it, you get an alert.
- **History** keeps every report for a year, each compared with the previous issue, so a change in the DKIM signing domain or the sending IP shows up on the first issue it affects.

See [monitoring](https://sendscore.ai/docs/monitoring/).

## What a verdict can't tell you

A verdict proves the message arrived at SendScore, and checks what arrived. It says nothing about whether Gmail, Outlook, or Yahoo put the same message in the inbox or in spam, and SendScore never reports a placement percentage. Every verdict carries a note saying so.