MAmatrix
Account management

Begins the validation process for an email address for association with the user's account.

The homeserver must check that the given email address is not already associated with an account on this homeserver. This API should be used to request validation tokens when adding an email address to an account. This API's parameters and response are identical to that of the /register/email/requestToken endpoint. The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over.

post/_matrix/client/v3/account/3pid/email/requestToken

Request

Request body

client_secretstring required

A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.

emailstring email required

The email address to validate.

next_linkstring uri

Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.

send_attemptinteger required

The server will only send an email if the send_attempt is a number greater than the most recent one which it has seen, scoped to that email + client_secret pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. If they do not, the server should respond with success but not resend the email.

id_access_tokenstring

An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.

Required if an id_server is supplied.

id_serverstring

The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification.

This parameter is deprecated with a plan to be removed in a future specification version for /account/password and /register requests.

Example request

{
  "client_secret": "monkeys_are_GREAT",
  "email": "alice@example.org",
  "next_link": "https://example.org/congratulations.html",
  "send_attempt": 1,
  "id_server": "id.example.com"
}

Response

An email was sent to the given address. Note that this may be an email containing the validation token or it may be informing the user of an error.

sidstring required

The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty.

submit_urlstring uri

An optional field containing a URL where the client must submit the validation token, with identical request and response parameters and error codes to the Identity Service API's POST /validate/email/submitToken and POST /validate/msisdn/submitToken endpoints (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client.

If this field is not present, the client can assume that verification will happen without the client's involvement provided the homeserver advertises a sufficiently recent version in the GET /versions response (ie: r0.5.0).

Example response

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

Changes

No recorded changes to this operation across all 1 revision of this API.