All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading