Requesting an email verification link

Requesting an email verification link

Contents

• Overview
• Permissions and Authentication
• Headers
• HTTP Parameters
• Sample request
• Sample response
• Possible error responses

Overview

• Call name: email-verify-request
• Endpoint URL: https://{API hostname}/auth/email-verify-request
• Request methods: POST
• Request Content-Types: application/x-www-form-urlencoded
• Response Content-Type: application/json
• Auth required: yes

Requests an email containing a verification link to be sent to a user, so that the user can confirm the email address on their account. Opening the link and calling email-verify completes the flow and sets the user's email_status to 1 (verified).

The link carries a signed, single-use verification token which is valid for 3 days. Requesting a new email does not invalidate links from earlier emails: each link stays valid until it is used or expires.

This flow is only available for chains whose email_verification_method is set to deeplink (see alter-chain). Chains configured for otp should use otp-request and otp-verify instead. For an overview of both flows, see Verifying user contact details.

No email address is passed to this endpoint: the address which receives the email is the one already stored on the account. Requests are rate limited to one per 60 seconds, counted both per email address per chain and per user per chain.

Permissions and Authentication

This API call requires a valid Spaaza session. The session can be as follows:

• User authentication: a session generated by an end-user login. The session user must be the user identified by user_id.
• Admin authentication: the performing user needs to be logged in and have write access to the chain to which the user is connected.

Headers

The following headers can/must be passed to the API call:

Parameter	Description
X-Spaaza-Session-User-Id	(mandatory) The user ID of the session, see Authentication.
X-Spaaza-Session-Key	(mandatory) The session key of the session, see Authentication.
X-Spaaza-API-Version	(optional) The API version, see versioning.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter	Description
user_id	(integer, mandatory) The ID of the user whose email address should be verified.
chain_id	(integer, mandatory) The ID of the chain the user belongs to.

The target user is identified by user_id and chain_id only. Because no email address is accepted as input, the response cannot be used to discover which email addresses have accounts.

Sample request

POST https://{API hostname}/auth/email-verify-request
Content-Type: application/x-www-form-urlencoded

user_id=3635922&chain_id=1743

Sample response

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "message": "An email verification message has been sent to your email address.",
        "result_type": "email-verify-request"
    }
}

Possible error responses

The following represents a list of possible error responses for the email-verify-request endpoint:

Code	Name and Description	HTTP Status Code
3	http_vars_missing The user_id or chain_id parameter is missing or is not an integer.	400
6	no_valid_session The user needs to be logged in and a valid session key needs to be sent.	401
424	access_denied The session user does not match the target user and does not have admin privileges on the chain.	403
557	email_verification_rate_limit_exceeded The rate limit for email verification has been exceeded.	400
558	email_verification_mismatch No user was found for the user_id, or the user does not belong to the chain_id.	409
559	email_verification_not_enabled The chain's email_verification_method is not set to deeplink.	400