# Sessy

Sessy is an open source email observability dashboard for Amazon SES

[Sessy](https://github.com/marckohlbrugge/sessy) is a Ruby on Rails 8 application by Marc Köhlbrugge that shows what happens to email you send through raw Amazon SES: deliveries, bounces, complaints, opens and clicks. It replaces paid email dashboards that are wrappers around SES. SES pushes events to Sessy over SNS webhooks, so Sessy never needs your AWS credentials. It uses SQLite by default with Solid Queue, Solid Cache and Solid Cable, so it deploys on Hatchbox with no extra services.

## Requirements

None by default. Sessy stores its SQLite databases in `storage/`, which Hatchbox keeps in `shared/storage` across deploys. Use a single-server cluster.

If you would rather use PostgreSQL, create a PostgreSQL database on the app's Databases tab. Sessy switches to the PostgreSQL adapter automatically when `DATABASE_URL` starts with `postgres`.

## Repository

Set the Git URL to the GitHub repository:

```
https://github.com/marckohlbrugge/sessy.git
```

And use the `main` branch. Sessy has no tagged releases; `main` is what upstream ships as its Docker image.

## Environment Variables

Add these on the Environment tab before the first deploy:

```
HTTP_AUTH_USERNAME=admin
HTTP_AUTH_PASSWORD=choose-a-strong-password
```

Sessy protects the dashboard with HTTP Basic auth when both variables are set. Without them anyone can read your email data, and Sessy shows a warning banner. Webhook endpoints stay open so SES can deliver events.

Hatchbox generates `SECRET_KEY_BASE` and sets `RAILS_ENV=production` for you. Sessy expects to run behind an SSL-terminating proxy, which Hatchbox's Caddy provides, so leave `DISABLE_SSL` unset.

Optional:

```
DISABLE_UPDATE_CHECKS=true
MISSION_CONTROL_USERNAME=admin
MISSION_CONTROL_PASSWORD=choose-a-strong-password
```

`MISSION_CONTROL_*` protect the Solid Queue dashboard at `/jobs`; they fall back to the `HTTP_AUTH_*` values.

## Processes

Hatchbox detects the Rails server and Solid Queue automatically and adds both processes on the first deploy: `bin/rails server` and `bin/jobs`.

## First Login

Open your domain and sign in with the `HTTP_AUTH_USERNAME` and `HTTP_AUTH_PASSWORD` you set. There are no user accounts in the self-hosted edition.

Then add a source for each app that sends email and follow the in-app setup tab, which gives you the webhook URL plus the SES configuration set and SNS topic to create in AWS. Upstream's [AWS SES setup guide](https://github.com/marckohlbrugge/sessy/blob/main/docs/aws-ses-setup.md) covers the same steps with the AWS CLI.

## Notes

Sessy ships an MCP server at `/mcp` that authenticates with API keys created in the web UI. It ignores the HTTP Basic auth variables.

To update, deploy again. Hatchbox runs pending migrations on each deploy.