Skip to content

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 The PDS: accounts and their records; accounts, their emails and passwords are as Accounts says, and sessions as Sessions 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 Account lifecycle (“Its own calls”).

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): both are false, and it can have neither.

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). Account lifecycle adds delete_account, and Moving an account between servers 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, Account lifecycle’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.

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

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 {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): 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.

createSession (Accounts) 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 {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 {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), 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 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): 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 (Account lifecycle): 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: the authorization server, “Devices”). Every passkey of the account is removed, and its link to add one ended (Passkeys, “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.

Every email the server sends goes through one mailer, as one of these kinds, each with its token:

KindSent byToken’s purposeSubject
confirmEmailrequestEmailConfirmationconfirm_emailEmail Confirmation
updateEmailrequestEmailUpdate; updateEmail turning the factor offupdate_emailEmail Update Requested
resetPasswordrequestPasswordResetreset_passwordPassword Reset Requested
signInAuthFactorcreateSessionauth_factorSign-in Confirmation
deleteAccountrequestAccountDelete (Account lifecycle)delete_accountAccount Deletion Requested
plcOperationrequestPlcOperationSignature (Moving an account between servers)plc_operationPLC Update Operation Requested

No other method sends email: not createAccount, nor updateEmail when it changes the email.

VariableDescription
PDS_EMAIL_SMTP_URLthe 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_FROMthe 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.

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: what the authorization pages show), 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.
KindHeading
confirmEmailConfirm your email
updateEmailChange your email
resetPasswordReset your password
signInAuthFactorYour sign-in code
deleteAccountDelete your account
plcOperationConfirm 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.

VariableDescription
PDS_DEV_MAIL_DIRoptional: 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": <address>, "kind": <kind>, "token": <token>}, the address as the account keeps it, in lower case;
  • it is written under a name starting with ., and renamed into place, to <name>.json;
  • each name sorts after every earlier one’s in that directory, also after a restart: the time in nanoseconds since the epoch, as 20 digits, -, and a counter, does.

The server does not read the directory, nor remove what it wrote. Unset, it writes nothing anywhere.

Note: it is for the harness, and for development: an operator leaves it unset.

With PDS_RATE_LIMITS_ENABLED (Limits), these methods have limits of their own, by the rules of Limits’s “Rate limits”: when a call costs points, windows, the client address, the headers and the 429. Each also costs one point of global. Each limit is the method’s own: the two requestEmail* methods do not share theirs.

In the table’s order, as Limits uses it for the headers and the 429 (the day’s limit before the hour’s, as login, day comes before login):

LimitMethodsKeyPointsWindow
email confirmation, dayrequestEmailConfirmationthe token’s DID1586400 s
email confirmation, hourrequestEmailConfirmationthe token’s DID53600 s
email update, dayrequestEmailUpdatethe token’s DID1586400 s
email update, hourrequestEmailUpdatethe token’s DID53600 s
password reset, dayrequestPasswordResetclient address5086400 s
password reset, hourrequestPasswordResetclient address153600 s
resetresetPasswordclient address50300 s

confirmEmail and updateEmail have only global. A requestPasswordReset for an email no account has costs its points as one that finds one does.

As Durability says of every answered write: a token the server answered for, a confirmation, a changed email, the email factor turned on or off, a token used up, and a reset password, with the sessions, requests and device sign-ins it ended, all survive the server being killed. A token keeps its 15 minutes across a restart.

What the reference does that the server does not copy

Section titled “What the reference does that the server does not copy”
  • What a password reset leaves. The reference ends only the account’s password and app password sessions: its OAuth sessions still answer getSession and refresh, a code approved before is exchanged, and the devices it was signed in on still list it (probed). The server ends them all, as resetPassword says.

harness/compare.mjs starts the server with PDS_DEV_MAIL_DIR, an empty directory of its own, and catches the reference’s emails in its process, as its mailer is about to send them. After each call, it takes the emails each side sent during it, in order, and compares them by to and kind; each token must be of the form above. The harness then uses each side’s own tokens. Before each step of this page it also takes the emails sent since the last, and compares them the same way, so that no other method sends one where the reference does not.

Each step picks an account, and keeps the tokens each side mailed it, by purpose, current or replaced, to give back later, maybe after a crash:

  • requestEmailConfirmation with the account’s access token, none, its refresh token, or one never given out.
  • confirmEmail with the account’s email, in mixed case, another account’s, or none of the input; and its current confirm_email token, an earlier one, the current one in lower case, a token of another purpose, one never made, or "". Then getSession, compared.
  • requestEmailUpdate, and updateEmail to a new address (at the edges of what createAccount takes too), the same address, in mixed case, another account’s, one only an account without a password had, or one that is not an address; with no token, the current update_email token, an earlier one, the current one in lower case, another purpose’s, one never made, or ""; sometimes with emailAuthFactor: false, and with emailAuthFactor: true and another address. Then getSession, compared, and createSession by the new email.
  • the email factor, in one step: updateEmail turning it on, for an account confirmed or not; createSession with the password and no code, with a code replaced since, one never made, another purpose’s, with an app password, and with the code, once and again; then updateEmail turning it off, without a token, with a wrong one, and with the one mailed. The factor is off again when the step ends, so that the other steps’ createSessions are not asked for codes.
  • requestPasswordReset by the account’s email in mixed case, an email no account has, an account’s without a password, or a string that is no address; and resetPassword with the current token, an earlier one, the current one in lower case, another account’s (which resets that account’s password), another purpose’s, or one never made; a new password, one of 256 UTF-16 units, one over, or "" (then set again by a second reset in the same step). Then createSession with the old and the new password, and refreshSession with a session’s refresh token from before, all compared. Sometimes, before the reset, the account signs in through OAuth and has a request approved; after it, held to this page on the server alone: getSession with each of its OAuth sessions (401 invalid_token), a refresh of each public client’s (400 invalid_grant), the approved request’s code (400 invalid_grant), and the page on each device it signed in on, which lists it no more. The harness then drops those sessions and devices on both sides.
  • app passwords and these methods: each of the four that take a token, called with an app password’s session made for the step.
  • SMTP refusing: with the harness’s SMTP sink refusing every message, requestEmailConfirmation or requestPasswordReset: where the reference answers 200, the server 500 InternalServerError, its email in the development sink all the same; then the token not delivered used, confirmEmail and getSession, or resetPassword and createSession with the old password and the new, compared.

The server is also given PDS_EMAIL_SMTP_URL, the harness’s SMTP sink on the loopback with a user and password to percent-decode, and PDS_EMAIL_FROM, and held to “SMTP” and “The message” on the server alone: every email the development sink takes arrives over SMTP once, logged in, from PDS_EMAIL_FROM in the envelope and From:, to the account’s email in the envelope and To:, with its kind’s subject; as multipart/alternative of a text/plain part and a text/html part, in that order, the token in each; the HTML part’s text holding the server’s host and the kind’s heading, and no src, href or url( naming anything to load; and no message arrives that the development sink did not take. The end of every run starts the server with one of the two variables and not the other: it must exit 1, with pds: and why on standard error.

Accounts with a password change email and password as the reference’s do, and the harness follows: other steps log in with the new password and email.

Not compared:

  • ExpiredToken for a token past its 15 minutes: the harness does not wait 15 minutes.
  • The reference’s subject, sender, body and HTML, and its SMTP: only the address it goes to, its kind, and its token’s form. smtps:// and STARTTLS: the sink offers neither.
  • Calls at once with one token: which wins is a race, and the reference lets several resetPasswords through.
  • Disposable-mail domains, which the reference refuses from its list.
  • The rate limits above in this run, which has them off on both sides: Limits’s --limits run checks them.