All jobs

Add Email Verification to an AdonisJS App

Yes. An agent adds signed verification links, a verified-at column and a guard middleware to your AdonisJS app, tests it with a faked mailer, 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 the signup path it is about to extend before it adds a verification step to it. In an app laid out like the hypermedia kit in adonisjs/starter-kits, app/controllers/new_account_controller.ts validates the form with signupValidator, calls User.create({ fullName, email, password }), logs the user in with auth.use('web').login(user) and redirects to dashboard. start/routes.ts keeps signup and login in a guest group and /dashboard and logout in an auth group, both named in start/kernel.ts. The users table comes from database/migrations/1758943358073_create_users_table.ts, with id, a nullable full_name, a unique email, password and the two timestamps, and database/schema.ts is generated from it by node ace migration:run, so a new column means a migration and a regenerated schema rather than an edit to the model. start/env.ts validates APP_URL, and package.json has no mail package even though its imports map reserves #mails/*.

The agent runs node ace add @adonisjs/mail --transports=smtp, which registers the provider in adonisrc.ts and adds SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, MAIL_MAILER, MAIL_FROM_ADDRESS and MAIL_FROM_NAME to start/env.ts and .env.example. A migration adds a nullable email_verified_at timestamp to users, and node ace migration:run regenerates UserSchema with the new column. node ace make:mail verify_email creates app/mails/verify_email_notification.ts, whose prepare() sets the recipient and renders resources/views/emails/verify_email.edge with a link made by signedUrlFor from @adonisjs/core/services/url_builder, pointing at a route named verification.verify with the user's id as a parameter, expiresIn: '1 day' and prefixUrl from env.get('APP_URL'), since a link in an email has to be absolute.

The controller and the guard are small. app/controllers/email_verification_controller.ts has notice, which renders a page telling the user to check their inbox; verify, on GET /verify-email/:id, which answers 400 when request.hasValidSignature() is false, loads the user, sets emailVerifiedAt to DateTime.now() when it is still null, flashes a success message through the partials/flash_alerts.edge the layouts already include, and redirects to the dashboard when that browser is signed in and to login otherwise; and resend, a POST in the auth group that queues the mail again with mail.sendLater. NewAccountController.store queues the same mail right after User.create. A verified middleware in app/middleware/verified_middleware.ts, added to the named list in start/kernel.ts, redirects a signed-in user with a null emailVerifiedAt to the notice page, and the /dashboard route takes it after auth(). The notice page uses the kit's @form and @button components, so the resend button carries the CSRF token @adonisjs/shield checks on every POST.

Tests go in tests/functional/email_verification.spec.ts under the functional suite from adonisrc.ts, which tests/bootstrap.ts starts an HTTP server for. With using fake = mail.fake(), one test posts the signup form with withCsrfToken(), asserts the mail was queued for that address with fake.mails.assertQueued, builds the same signed URL with signedUrlFor, follows it and asserts the row's email_verified_at is set with the database assertions already registered in tests/bootstrap.ts. A second test changes one character of the signature and expects 400; a third signs in as an unverified user and expects /dashboard to redirect to the notice page. The agent runs npm run lint, npm run typecheck and node ace test in its sandbox, since .github/workflows/ci.yml runs the first two and not the third, and keeps the output.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add email verification to this AdonisJS 7 app. Read package.json, adonisrc.ts, .env.example, start/env.ts, start/routes.ts, start/kernel.ts, config/auth.ts, config/shield.ts, app/controllers, app/models/user.ts, app/validators/user.ts, database/migrations, database/schema.ts, the views under resources/views and tests/bootstrap.ts first. Run node ace add @adonisjs/mail --transports=smtp. Add a migration for a nullable email_verified_at timestamp and run node ace migration:run so database/schema.ts is regenerated. Make a verify_email mail class whose template links to a route named verification.verify through signedUrlFor with expiresIn of one day and prefixUrl from APP_URL. Add an EmailVerification controller with notice, verify and resend actions: verify answers 400 unless request.hasValidSignature(), sets the timestamp, flashes success and redirects. Queue the mail with mail.sendLater after User.create in the signup controller. Add a verified named middleware that sends unverified users to the notice page and apply it to /dashboard. Write functional tests with mail.fake() that sign up, assert the queued mail, follow the signed link, reject a tampered signature and check the dashboard redirect. Run npm run lint, npm run typecheck and node ace test and quote the output. Open a pull request.",
  "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 adds the migration, app/mails/verify_email_notification.ts, resources/views/emails/verify_email.edge, app/controllers/email_verification_controller.ts, app/middleware/verified_middleware.ts, resources/views/pages/auth/verify_email.edge and tests/functional/email_verification.spec.ts, and changes package.json, adonisrc.ts, start/env.ts, .env.example, config/mail.ts, database/schema.ts, start/routes.ts, start/kernel.ts, app/controllers/new_account_controller.ts and .adonisjs/server/controllers.ts, the generated controller index. Its description quotes the lint, typecheck and test output and shows the signed link shape.

A reviewer signs up on the branch with an SMTP catcher's values in .env, opens the mail, follows the link once and sees the dashboard, follows it a second time and sees the success flash with no second write, then edits the signature in the address bar and gets the 400. In the code they check two things: that the verify route does not log anyone in by itself, and that resend is inside the auth group so a stranger cannot make the app send mail to an arbitrary address.

Login is unchanged. An unverified user can still sign in; the verified middleware only keeps them off /dashboard and any route a reviewer later adds it to.

Run it on every Linear issue labelled auth

A team that keeps account features in Linear starts one run per issue from a handler on its own server: when an issue gains the auth label, the handler sends this body to POST /o/{org}/sessions with the repository in resources and the issue's https://linear.app/<workspace>/issue/<ID> URL as a second resource, with a request_id that is a UUID v5 of the issue id so a redelivery returns the run already started. The prompt tells the agent to reuse the mail configuration and the verified middleware once they exist.

A Rush automation with a linear trigger on linear.issue.labeled can watch the same label, but its runs are read-only: they read the repository and comment rather than push. That suits a plan comment listing the routes, migration and views the change would touch, with the handler above starting the run that opens the pull request.

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

Why run it on Rush?

An email flow has three parts that only a real run can prove: the mail is queued, the signed link verifies, and a tampered link does not. The agent runs node ace test with the faked mailer in its own sandbox, follows the link it built itself, and keeps every command and its output with the pull request, so the reviewer reads a passing suite before reading the controller.

Each AdonisJS app a team runs has its own validators, views and migrations. One request per repository, started at once, gives each a pull request written against its own NewAccountController and users table, rather than a snippet pasted from a guide.

Frequently asked questions

Why signed URLs instead of a token table?

signedUrlFor signs the route, its parameters and an expiry with the app key, and request.hasValidSignature() checks both the signature and the expiry, so no token row is written or cleaned up. A table is the right choice when a link must be revocable one at a time, which the pull request notes.

Does the migration touch database/schema.ts by hand?

No. That file says it is generated, and node ace migration:run rewrites UserSchema with the new emailVerifiedAt column. The User model in app/models/user.ts keeps composing the generated schema with withAuthFinder, so nothing is edited there.

What sends the mail in development?

The SMTP transport from node ace add @adonisjs/mail --transports=smtp, with the host, port and credentials in .env. mail.sendLater queues it so the signup response is not slowed by the delivery; .env.example documents the keys and the pull request suggests a local catcher for development.

Can an unverified user still log in?

Yes. SessionController.store is unchanged. The verified middleware is applied to /dashboard, and a reviewer adds it to any other route that should wait for a confirmed address.

Will CI run the new tests?

Not as the workflow stands: .github/workflows/ci.yml runs npm run lint and npm run typecheck for each kit and no node ace test. The pull request says so and leaves adding a test step to a separate change, since it affects all three kits in the matrix.

More AdonisJS jobs

The same job on other stacks

Keep reading