Sessy / Docs

How Sessy works

Amazon SES already knows what happened to every email you send. Sessy listens to those events and turns them into a dashboard you can search. It is not in your sending path, and it never needs access to your AWS account.

The event flow

  1. Your app

    Sends through SES as usual

  2. Amazon SES

    Configuration set

  3. Amazon SNS

    Topic, pushes over HTTPS

  4. Sessy

    Signed webhook, one per source

  5. You and your agents

    Dashboard, CSV, MCP

  1. 1 Your app sends email through SES with a configuration set. Nothing about sending changes.
  2. 2 SES publishes an event for every send, delivery, bounce, complaint, open, click, reject, delay, rendering failure and subscription change to an SNS topic in your account.
  3. 3 SNS posts each event to the webhook URL of a Sessy source. Sessy verifies the SNS signature, stores the event and ignores duplicates.
  4. 4 You search and filter in the dashboard, export CSV, or let a coding agent query the same data over MCP.

What this design gives you

No AWS credentials
AWS pushes events to Sessy. Sessy holds no access keys and needs no IAM user or role, so there is nothing to rotate and nothing to leak.
One click on the AWS side
Each source opens a pre-filled CloudFormation stack that creates the configuration set, SNS topic, subscription and event destination. You can also copy the CLI commands, or hand the instructions to your coding agent.
One container
Sessy runs as a single Docker container with SQLite. PostgreSQL is optional. There is no Redis, no message queue and no separate worker to operate.
Many sources, one dashboard
Create a source per app, environment or mail stream. Each has its own webhook URL, stats and retention period, and sources can live in different AWS accounts and regions.
Detail per recipient
Every event is stored per recipient, so a message to five people shows five outcomes. Bounces keep their type, subtype and the receiving server's diagnostic.
Reputation in context
Bounce and complaint rates are shown against the levels where AWS reviews an account and where it may pause sending.
Built for agents
Every instance serves an MCP endpoint. Agents can search events, read a message's timeline, pull stats and set up a new source. Email data is read-only.
Yours to run or ours
Sessy is open source. Self-host it, or use the hosted version, which runs the same code.

How it compares to other ways of watching SES

SES can deliver its events in a few ways, and the tools built on SES follow one of them. Each choice decides what you have to run and what the tool is allowed to touch.

Question Sessy (SNS webhook) Queue polling (SNS to SQS, a worker polls) Firehose to S3, queried with Athena CloudWatch metrics
AWS access the tool needs None. No access keys, no IAM user or role. An IAM user or role that can read and delete from the queue. IAM roles for Firehose, S3 and Athena. Console or API access to the account.
What you run One container. SQLite by default. A web app, a polling worker and a database. Nothing, but there is no interface. You write SQL. Nothing.
Search one message or one recipient Yes, with the full event timeline and bounce diagnostics. Yes, depending on the tool. Yes, as SQL queries that you write and pay for per scan. No. Totals and rates only.
Several apps, AWS accounts or regions Yes. One source each, in a single dashboard. Usually one queue, so one account and region per install. Possible. You build it. Separate per account and region.
Public HTTPS endpoint Required when self-hosting. The hosted version provides it. Not needed. Not needed. Not needed.
If the receiver is offline SNS retries for a limited time. The queue holds events for days. Not applicable. Events land in S3. Not applicable.
Setup on the AWS side One CloudFormation stack, opened pre-filled from Sessy. Topic, queue, queue policy and IAM credentials. Delivery stream, bucket, table definitions and IAM roles. An event destination, plus dashboards and alarms you define.

When another approach fits better

  • Your dashboard must stay on a private network with no inbound traffic. A webhook needs a public HTTPS endpoint. Use a queue-polling tool, or the hosted version of Sessy, which receives the webhooks for you.
  • You want SES events in a data lake next to everything else. Firehose to S3 with Athena is built for that. You give up the interface.
  • You only need an alarm on account-level bounce and complaint rates. CloudWatch does that on its own.

For the common case, a team that sends through SES and wants to know what happened to an email without adding infrastructure, the webhook is the smallest thing that works.

Frequently asked

Does Sessy send email?

No. Your app keeps sending through SES directly. If Sessy is offline, your email still goes out.

Can Sessy read my emails?

SES events carry the subject, sender, recipients and headers of a message, not its body. That is all Sessy receives.

What happens while Sessy is down?

SNS retries each event for a limited time, and Sessy ignores anything it has already stored. Events from a longer outage are not replayed, so run Sessy like any service that receives webhooks.

Can anyone post fake events to my webhook?

No. Each source has an unguessable URL, and Sessy rejects any request that is not signed by Amazon SNS.

Next steps