# Add Email Verification to a FastAPI App on SQLModel

Yes. An agent adds a verified-at column, a signed link sent at signup, a verify route and a login check, migrates existing users, tests it and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-email-verification/sqlmodel/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how accounts are made before adding a step. In an app made from fastapi/full-stack-fastapi-template, `backend/app/api/routes/users.py` has `POST /users/signup`, which checks the email is unused and calls `crud.create_user` at once; `UserBase` in `models.py` defaults `is_active` to `True`, and there is no verified flag anywhere. The superuser route `POST /users/` already sends mail through `generate_new_account_email` when `settings.emails_enabled`, which `core/config.py` defines as `SMTP_HOST and EMAILS_FROM_EMAIL`. `api/routes/login.py` shows the pattern for a signed link: `generate_password_reset_token` in `utils.py` signs `{"exp", "nbf", "sub": email}` with `SECRET_KEY` for `EMAIL_RESET_TOKEN_EXPIRE_HOURS` (48), and `verify_password_reset_token` decodes it. Templates live in `email-templates/` and `render_email_template` fills them. `compose.override.yml` runs Mailpit with `SMTP_HOST: "mailpit"` for local mail, and `tests/api/routes/test_login.py` patches `settings.SMTP_HOST` to exercise a mail-sending route. The frontend's `useAuth.ts` sends a signup straight to `/login`.

The change starts in `models.py`: `User` gains `email_verified_at: datetime | None`, and `UserPublic` exposes it so the frontend can tell. The Alembic migration adds the column and then sets it to `now()` for every existing row, so nobody who already has an account is locked out by the deploy. In `utils.py` the agent adds `generate_email_verification_token(email)` and its verify function, and gives both this token and the password reset token a `purpose` claim that each verifier checks, so a reset link can never verify an address and a verification link can never reset a password. A `verify_email.html` template joins the three existing ones.

Routes follow. `POST /users/signup` creates the user and, when `emails_enabled`, sends the verification link to `settings.FRONTEND_HOST` with the token in the query string. `POST /users/verify-email` takes `{"token"}`, sets `email_verified_at` and answers a `Message`. `POST /users/resend-verification` answers the same message whether or not the address exists, the way `recover_password` already avoids email enumeration. `POST /login/access-token` refuses a user with no `email_verified_at` with a 400 beside its existing `Inactive user` branch, and users made by a superuser through `POST /users/` or by `init_db` are marked verified at creation, since an admin vouched for them. On the frontend, a `/verify-email` route reads the token from the URL and calls the new endpoint, and the signup success message says to check the inbox.

Tests sit beside the existing ones: signup leaves `email_verified_at` empty, login answers 400 until the token is used, the token verifies once, a reset token is refused by the verify route, and resend answers the same message for an unknown address. For the proof the sandbox has no Docker for Postgres or Mailpit, so the agent installs Postgres with `apt-get`, runs a small SMTP debugging server that prints what it receives, points `SMTP_HOST` at it, and walks the flow with `curl`: signup, the printed mail with its link, verify, login. Then `uv run bash scripts/prestart.sh`, `uv run bash scripts/test.sh`, `uv run ruff check` and `uv run mypy app`, keeping coverage above the 90% the workflow enforces.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Signup creates an active user without checking the address. Add email verification: an email_verified_at column on User, exposed in UserPublic, with an Alembic migration that backfills existing users as verified. Add a signed verification token in utils.py in the style of the password reset token, and give both tokens a purpose claim that each verifier checks. On signup, send a verification email with a link to FRONTEND_HOST when emails are enabled; add POST /users/verify-email taking the token and POST /users/resend-verification that answers the same message for any address. Refuse login for an unverified user with a 400 beside the Inactive user branch; users created by a superuser or by init_db are verified at creation. Add a frontend route that verifies from the link. Write tests for signup, the login refusal, verification, a reset token being refused, and resend. Prove the flow against a local Postgres and a local SMTP debug server with curl, then run prestart.sh, test.sh, ruff and mypy. Open a pull request quoting the mail, the curl answers and the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `backend/app/models.py`, `utils.py`, `api/routes/users.py`, `api/routes/login.py`, `core/db.py`, adds a migration under `app/alembic/versions` and `email-templates/verify_email.html`, extends `tests/api/routes/test_users.py` and `test_login.py`, and adds the frontend route with the regenerated client. Its description quotes the printed verification mail, the `curl` answers for signup, verify and login, and the pytest output with its coverage total.

A reviewer checks the migration's backfill so existing users keep signing in, that the two token kinds cannot be swapped, and that the resend route gives nothing away about which addresses exist. The transcript at GET /o/{org}/sessions/{id}/messages has the SMTP server output and every request of the walk-through.

Mail only goes out where `emails_enabled` is true, as today; in a deployment with no SMTP settings, signup still creates the user and the pull request says that login will refuse them until SMTP is configured.

## Run it on every new service on the template

Every service started from the same template has the same open signup, so each one is this run on its own repository. Send POST /o/{org}/sessions with this body once per service, with a `request_id` that is a UUID v5 of the repository name so a retried send returns the run it already started rather than a second pull request.

A webhook URL on the API key delivers `run.completed` when each run finishes, with the `session_url` to read its pull request from. A service that already has a verified column comes back with a result saying so and no pull request.

## Why run it on Rush?

Verification is a small feature with a wide blast radius: a wrong migration locks every existing user out, and a token that doubles as a reset link is a security hole. The convincing proof is the whole flow walked against a real Postgres and a real SMTP endpoint, with the mail body and each response in the record, and then the full suite with coverage above the number CI enforces. The sandbox has both services for the run and nothing of yours is involved.

Several services are several runs, in parallel, each on its own branch with its own walk-through. A reviewer reads one diff per service and the same four `curl` answers in each description.

## Frequently asked questions

### Will existing users have to verify?

No. The migration backfills `email_verified_at` for every row that exists when it runs, so only accounts created after the deploy go through the link. If you would rather re-verify everyone, say so in the prompt and the migration leaves the column empty.

### What happens when SMTP is not configured?

The same as the template's password recovery today: `emails_enabled` is false, no mail is sent, and signup still creates the user. Login then refuses them with the unverified message, which is why the pull request calls out that production needs `SMTP_HOST` and `EMAILS_FROM_EMAIL` set before this merges.

### Why a purpose claim on both tokens?

Both are signed with the same `SECRET_KEY` and both carry the email as `sub`. Without a claim that says what the token is for, a verification link could be posted to the reset route. Each verifier checks its own purpose and refuses the other.

### How is the flow proved without Mailpit?

The sandbox cannot run the Compose services, so the agent starts an SMTP debugging server that prints each message to its console, points `SMTP_HOST` at it, and reads the link from the printed mail. CI and local development keep using Mailpit from `compose.override.yml`.

## More SQLModel jobs

- [Add Full-Text Search to a SQLModel and FastAPI App](https://getrush.ai/run/add-full-text-search/sqlmodel/)
- [Add Optimistic Locking to SQLModel Updates](https://getrush.ai/run/add-optimistic-locking/sqlmodel/)
- [Add Refresh Tokens to a FastAPI App on SQLModel](https://getrush.ai/run/add-refresh-tokens/sqlmodel/)

## The same job on other stacks

- [Add Email Verification to an AdonisJS App](https://getrush.ai/run/add-email-verification/adonisjs/)
- [Add Email Verification to a Django REST Framework Project](https://getrush.ai/run/add-email-verification/django-rest-framework/)
- [Add Email Verification to a Filament Panel from a Linear Issue](https://getrush.ai/run/add-email-verification/filament/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
