# Email What the server does with an account's email: confirming it, changing it, resetting the password by it, and signing in with a code sent to it; the tokens it mails for each; and the mailer that sends them. What every method shares, and how the server is checked, is in [`PDS.md`](PDS.md); accounts, their emails and passwords are as [`ACCOUNTS.md`](ACCOUNTS.md) says, and sessions as [`SESSIONS.md`](SESSIONS.md) says. The methods: `com.atproto.server.requestEmailConfirmation`, `confirmEmail`, `requestEmailUpdate`, `updateEmail`, `requestPasswordReset` and `resetPassword`; and of `createSession`, its `authFactorToken`. What a deactivated, taken-down or deleted account's calls of them answer is in [`LIFECYCLE.md`](LIFECYCLE.md) ("Its own calls"). ## The account's email An account created with a password keeps its email, in lower case, and two facts about it, both `false` when the account is made: - **confirmed**: whether its owner has shown they read mail sent to it (`confirmEmail`). Changing the email makes it unconfirmed again, even to the same address. - **the email factor**: whether signing in with the account's password also needs a code mailed to the email (below). Only a confirmed email may have it, and changing the email turns it off. `getSession`, `createSession` and `refreshSession` answer them as `emailConfirmed` and `emailAuthFactor`. An account created without a password keeps no email (`ACCOUNTS.md`): both are `false`, and it can have neither. ## Tokens Each email the server sends for an account carries a token, which the account's owner gives back to the server to show they read it: - **Form.** Two groups of five characters, each an upper case letter or a digit 2 to 7, joined by `-`, as `AB2CD-EF7GH`: ten characters of base32 (RFC 4648's alphabet), from at least 50 random bits. - **Purpose.** Each token is for one purpose, and works for that alone: `confirm_email` (`confirmEmail`), `update_email` (`updateEmail`, both to change the email and to turn the email factor off), `reset_password` (`resetPassword`), and `auth_factor` (`createSession`'s `authFactorToken`). `LIFECYCLE.md` adds `delete_account`, and `MIGRATION.md` `plc_operation` (`signPlcOperation`). - **One at a time.** An account has at most one token of each purpose. Making one replaces the account's earlier token of that purpose, which then no longer works. - **Matching.** A token given is matched without regard to case, so `ab2cd-ef7gh` is `AB2CD-EF7GH`; otherwise exactly: without its `-`, or with spaces around it, it is wrong. - **Lifetime.** A token works for 15 minutes from when it was made. Given after that, it is `400 ExpiredToken`, and stays so until it is replaced or used up; a token that is not the account's of that purpose at all is `400 InvalidToken`. Both before anything else the method would change. - **Used once.** A token that does what it was for is used up: given again, it is `400 InvalidToken`. Of several calls at once with one token, one succeeds. A call refused for another reason, after its token was found good, leaves the token as it was. - **Changing the email** (`updateEmail`) ends every token the account has, of every purpose, `LIFECYCLE.md`'s too. An empty token, `""`, is the same as none where a token is optional (`updateEmail`, `createSession`), and a wrong one where it is required. The reference does one thing here that the server does not copy: several `resetPassword` calls at once with one token all succeed there, each setting the password. ## requestEmailConfirmation A procedure with no input, called by `POST` with an access token of the account, of any scope (an app password's session's too). It checks, in this order: 1. The token, as `SESSIONS.md` says: none is `401 AuthMissing`, one the server did not give out, or a refresh token, `400 InvalidToken`. 2. A request body is `400 InvalidRequest`. 3. An account created without a password, which keeps no email, is `400 InvalidRequest`. It then makes a `confirm_email` token, mails it to the account's email (kind `confirmEmail`, below), and answers `200` with an empty body. It does so whether or not the email is confirmed already. ## confirmEmail `confirmEmail` `{email, token}` is called with an access token of the account, of any scope. It checks, in this order: 1. The token, as above. 2. The input against the lexicon: `email` or `token` missing, or not a string, is `400 InvalidRequest`. 3. An `email` that, lowercased, is not the account's email is `400 InvalidEmail`; so is any `email` for an account without a password. 4. A `token` that is not the account's `confirm_email` token is `400 InvalidToken`, and one past its 15 minutes `400 ExpiredToken`. It then marks the email confirmed, uses the token up, and answers `200` with an empty body. Confirming an email that is confirmed already is allowed, and changes nothing else. ## requestEmailUpdate A procedure with no input, called by `POST`. Only a session of scope `com.atproto.access`, made with the account's own password, may call it: an app password's session, privileged or not, is `400 InvalidToken`. Then a request body is `400 InvalidRequest`, and an account without a password `400 InvalidRequest`. - If the account's email is confirmed, it makes an `update_email` token, mails it to the account's email as it is now (kind `updateEmail`), and answers `{tokenRequired: true}`. - If not, it makes no token, sends nothing, and answers `{tokenRequired: false}`. ## updateEmail `updateEmail` `{email, emailAuthFactor?, token?}` changes the account's email, or turns its email factor on or off. Like `requestEmailUpdate`, only a session of scope `com.atproto.access` may call it: an app password's session is `400 InvalidToken`. Then the input against the lexicon: `email` missing, or a field of the wrong type, is `400 InvalidRequest`. `email` is lowercased, and then: 1. **`emailAuthFactor: true`.** If the account's email is confirmed and is `email`, the factor is turned on (if it was not), and the call answers `200` with an empty body: the email does not change, and `token` is not looked at. Otherwise it is `400 InvalidRequest`. 2. **`emailAuthFactor: false`, with `email` the account's email.** If the factor is off, the call answers `200` and changes nothing. If it is on: - with no `token`, the server makes an `update_email` token, mails it to the email (kind `updateEmail`), and answers `400 TokenRequired`; - with one, it must be the account's `update_email` token (`400 InvalidToken`, `400 ExpiredToken`); the factor is turned off, the token used up, and the call answers `200`. The email does not change, and stays confirmed. 3. **Otherwise** (no `emailAuthFactor`, or `false` with another address), the email changes, after these checks: 1. `email` must be an address as step 3 of `createAccount` says (`ACCOUNTS.md`): one that is not is `400 InvalidRequest`. The reference also refuses disposable-mail domains; the server need not, and the harness sends none. 2. A `token`, if given, must be the account's `update_email` token (`400 InvalidToken`, `400 ExpiredToken`), whether or not one is needed. With none, an account whose email is confirmed is `400 TokenRequired`. 3. For an account without a password, the call answers `200` and changes nothing: it still keeps no email. That holds for an email another account has, too. 4. An email another account has is `400 InvalidRequest`, and leaves the token as it was. An account without a password keeps no email, so its email is no other account's. The account's email is then `email`, unconfirmed, with the email factor off; every token the account has is ended; and the call answers `200` with an empty body. That holds when `email` is the address it had: it is unconfirmed again. Nothing is mailed to the new address, nor to the old. So, when the email is confirmed, changing it takes two calls: one to `requestEmailUpdate`, and one to `updateEmail` with the token mailed to the old address. When it is not, `updateEmail` alone changes it. ## The email factor and createSession `createSession` (`ACCOUNTS.md`) takes an optional `authFactorToken`. After it has found the account and checked the password, so that a wrong one is still `401 AuthenticationRequired`: - With an `authFactorToken`, it must be the account's `auth_factor` token (`400 InvalidToken`, `400 ExpiredToken`), whether or not the factor is on, and whether the password is the account's or an app password's. It is used up, and the session made. - With none, if the account's email factor is on and the password is the account's own, the server makes an `auth_factor` token, mails it to the account's email (kind `signInAuthFactor`), and answers `401 AuthFactorTokenRequired`, making no session. An app password needs no code. ## requestPasswordReset `requestPasswordReset` `{email}` takes no token, and ignores one, even one the server did not give out. `email` missing or not a string is `400 InvalidRequest`. The email is lowercased; if no account with a password has it (an account without a password keeps none, and a string that is not an address is no account's), it is `400 InvalidRequest`. Otherwise the server makes a `reset_password` token for that account, mails it to the account's email (kind `resetPassword`), and answers `200` with an empty body. ## resetPassword `resetPassword` `{token, password}` takes no token, and ignores one. It checks, in this order: 1. The input against the lexicon: `token` or `password` missing, or not a string, is `400 InvalidRequest`. 2. A `password` longer than 256 UTF-16 code units, as `createAccount` counts it (`ACCOUNTS.md`), is `400 InvalidRequest`. 3. The token names its account: one that is no account's `reset_password` token is `400 InvalidToken`, and one past its 15 minutes `400 ExpiredToken`. The account's password is then `password`, hashed as `LIMITS.md` says ("Passwords"), and the token used up. The empty password is allowed here: `createSession` with `""` then logs in. Every session the account has is ended, those made with its app passwords too, as `deleteSession` ends one (`SESSIONS.md`): their refresh tokens are `400 ExpiredToken` from then on, and their access tokens work until they expire. Every OAuth session of the account ends too, as a takedown ends them (`LIFECYCLE.md`): their access tokens are `401 invalid_token` at once, and their refresh tokens `400 invalid_grant`. Every request approved for it whose code was not yet exchanged is ended, its code refused `400 invalid_grant`, and the account is signed out of every device it was signed in on (`OAUTH.md`, "Devices"). Every passkey of the account is removed, and its link to add one ended (`PASSKEYS.md`, "The account's states"). *Note:* a password reset is how an account is taken back from whoever had its password, and none of these may be left to them. The reference ends only the sessions above (below, "What the reference does that the server does not copy"). Its app passwords stay, and still log in. Its email, whether it is confirmed, its email factor, and its tokens of other purposes are as they were. It answers `200` with an empty body. ## The mailer Every email the server sends goes through one mailer, as one of these kinds, each with its token: | Kind | Sent by | Token's purpose | Subject | | --- | --- | --- | --- | | `confirmEmail` | `requestEmailConfirmation` | `confirm_email` | Email Confirmation | | `updateEmail` | `requestEmailUpdate`; `updateEmail` turning the factor off | `update_email` | Email Update Requested | | `resetPassword` | `requestPasswordReset` | `reset_password` | Password Reset Requested | | `signInAuthFactor` | `createSession` | `auth_factor` | Sign-in Confirmation | | `deleteAccount` | `requestAccountDelete` (`LIFECYCLE.md`) | `delete_account` | Account Deletion Requested | | `plcOperation` | `requestPlcOperationSignature` (`MIGRATION.md`) | `plc_operation` | PLC Update Operation Requested | No other method sends email: not `createAccount`, nor `updateEmail` when it changes the email. ### SMTP | Variable | Is | | --- | --- | | `PDS_EMAIL_SMTP_URL` | the SMTP server to send through: `smtp://[user:password@]host[:port]`, upgraded with STARTTLS when the server offers it, or `smtps://...` for TLS from the start; user and password percent-encoded | | `PDS_EMAIL_FROM` | the address each email is from | Both are set, or neither: one without the other makes `pds serve` exit 1, with `pds: ` and why on standard error. With both, each email is sent to the account's email, from `PDS_EMAIL_FROM`, with its kind's subject, as "The message" says. With neither, nothing is sent, and every method answers as if it had been. A token is kept before its email is sent. If sending fails, the method answers `500 InternalServerError`, and the token works all the same. ### The message Each email is one `multipart/alternative` message of two parts, in this order: 1. `text/plain; charset=utf-8`: a body that gives the token; the server may choose the rest of it. 2. `text/html; charset=utf-8`: the same email in the authorization pages' look (`OAUTH-PAGES.md`), from one template built with them in `web/` (`web/dist/email.html`), its styles written on its elements, as mail clients read them. It holds, as text: the server's host (`PDS_HOSTNAME`), the kind's heading below, the token, and that it works for 15 minutes, once; the server may choose the rest. | Kind | Heading | | --- | --- | | `confirmEmail` | Confirm your email | | `updateEmail` | Change your email | | `resetPassword` | Reset your password | | `signInAuthFactor` | Your sign-in code | | `deleteAccount` | Delete your account | | `plcOperation` | Confirm a change to your account | Nothing in the HTML part comes from the account or its request: no address, handle or name, so no text a person chose is drawn in the server's look. Every value the server puts in the template is escaped as HTML text. The part loads nothing: no image, stylesheet or font from anywhere, so opening it tells no one it was opened; a client that has the pages' typefaces draws them, and any other its own. ### The development sink | Variable | Is | | --- | --- | | `PDS_DEV_MAIL_DIR` | optional: a directory each email is also written to, for tests | With `PDS_DEV_MAIL_DIR` set, each email, sent through SMTP or not, is also written to that directory as a file of its own, before any SMTP sending, and before the method that sends it answers: - its content is JSON, `{"to":
, "kind":