Email Verification API Documentation

Use LaunchAlways as the delivery channel for one-time verification emails, then check submitted codes or query sent email records by the ID returned from the send endpoint.

outgoing_mail

1. Send Verification Email

Creates a sent email record, sends the fixed verification email, and returns a lookup ID.

LaunchAlways uses a fixed verification email template. Requests may only include the recipient email, verification code, code expiry window, and language; custom subject, text, HTML, or content fields are rejected.

POST/api/v1/email-verifications/send

Headers

Authorization: Bearer la_your_api_key_here
Content-Type: application/json

Request Body

Field	Type	Required	Nullable	Constraints	Description
`email`	string	Yes	No	Valid email address	Recipient email address. It is trimmed and normalized to lowercase.
`code`	string	Yes	No	1-8 characters	Verification code supplied by your application. Length must be 1-8 characters.
`expiresInMs`	number	Yes	No	Integer, 1000-86400000	Expiration window in milliseconds. Allowed range is 1000-86400000.
`language`	string	No	No	Enum: `en`, `zh-CN`, `zh-TW`, `es`, `fr`, `ja`, `ko`, `de`, `hi`, `ar`, `bn`, `pt`, `id`, `ur`	Email template language. Defaults to en when omitted.

Supported Languages

Value	Email language
`en`	English
`zh-CN`	中文
`zh-TW`	中文繁體
`es`	Español
`fr`	Français
`ja`	日本語
`ko`	한국어
`de`	Deutsch
`hi`	हिन्दी
`ar`	العربية
`bn`	বাংলা
`pt`	Português
`id`	Bahasa Indonesia
`ur`	اردو

Example

curl -X POST https://launchalways.com/api/v1/email-verifications/send \
  -H "Authorization: Bearer la_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "482913",
    "expiresInMs": 300000,
    "language": "en"
  }'

Success Response

{
  "ok": true,
  "emailId": "b7e4f7a3-0000-4000-9000-123456789abc",
  "language": "en",
  "expiresAt": "2026-06-08T12:34:56.789Z",
  "createdAt": "2026-06-08T12:29:56.789Z"
}

Success Response Fields

Field	Type	Required	Nullable	Constraints	Description
`ok`	boolean	Yes	No	Always true on success	Whether the send request completed successfully.
`emailId`	uuid	Yes	No	UUID string	Unique ID for querying this sent email record.
`language`	string	Yes	No	One of the supported language enum values	The language used to render and send this verification email.
`expiresAt`	ISO datetime	Yes	No	ISO 8601 timestamp	The absolute expiration time calculated from expiresInMs.
`createdAt`	ISO datetime	Yes	No	ISO 8601 timestamp	When LaunchAlways created the sent email record.

Error Responses

Status	Body	When it happens
`400`	`{"error":"<validation message>"}`	Invalid email, invalid code length, invalid expiry, unsupported language, malformed JSON, or rejected custom content fields.
`401`	`{"error":"Invalid or missing API key."}`	Missing, malformed, or unknown Bearer token.
`402`	`{"error":"Email verifications quota reached for the Free plan."}`	The account has used its monthly send quota. New emails are blocked, but existing verification records remain queryable.
`503`	`{"error":"RESEND_API_KEY is not configured."}`	The email provider is not configured.
`500`	`{"error":"<provider or server message>"}`	The provider request or database write failed after validation and quota checks.

fact_check

2. Check Verification Code

Checks a submitted recipient email and code against the stored hash, then returns the check result, email ID, record status, and result reason.

valid is true only when the submitted email and code match this record and the record has not expired. Mismatched or expired records return valid: false. The API key may only access records created for its own project; using an emailId from another project returns 404 with {"error":"Email record not found."}.

POST/api/v1/email-verifications/{emailId}

Headers

Authorization: Bearer la_your_api_key_here
Content-Type: application/json

Request Body

Field	Type	Required	Nullable	Constraints	Description
`email`	string	Yes	No	Valid email address	Recipient email address. It is trimmed and normalized to lowercase.
`code`	string	Yes	No	1-8 characters	Verification code supplied by your application. Length must be 1-8 characters.

Example

curl -X POST https://launchalways.com/api/v1/email-verifications/b7e4f7a3-0000-4000-9000-123456789abc \
  -H "Authorization: Bearer la_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "482913"
  }'

Success Response

{
  "valid": true,
  "emailId": "b7e4f7a3-0000-4000-9000-123456789abc",
  "status": "sent",
  "reason": "matched"
}

Success Response Fields

Field	Type	Required	Nullable	Constraints	Description
`valid`	boolean	Yes	No	true or false	true only when the submitted email and code match the stored record and the record has not expired; false when the code does not match, the email does not match, or the record is expired.
`emailId`	uuid	Yes	No	UUID string	Sent email record ID.
`status`	`sent` \| `expired`	Yes	No	Enum: sent, expired	sent before the expiry time, expired after the expiry time.
`reason`	string	Yes	No	Enum: matched, expired, email_mismatch, code_mismatch	Why the check returned its result: matched, expired, email_mismatch, or code_mismatch.

Error Responses

Status	Body	When it happens
`400`	`{"error":"<validation message>"}`	Invalid email, invalid code length, invalid expiry, unsupported language, malformed JSON, or rejected custom content fields.
`401`	`{"error":"Invalid or missing API key."}`	Missing, malformed, or unknown Bearer token.
`404`	`{"error":"Email record not found."}`	The lookup ID is invalid, missing, or belongs to another project.
`500`	`{"error":"Could not verify email code."}`	The record exists but could not be loaded because of a server error.

manage_search

3. Query Sent Email Record

Returns the recipient, validity window, language, status, and timestamps for a sent verification record.

This endpoint does not return the code, code hash, provider message ID, subject, HTML, or text body. The API key may only access records created for its own project; using an emailId from another project returns 404 with {"error":"Email record not found."}.

GET/api/v1/email-verifications/{emailId}

Headers

Authorization: Bearer la_your_api_key_here

Path Parameter

Field	Type	Required	Nullable	Constraints	Description
`emailId`	uuid	Yes	No	UUID string	The ID returned by the send endpoint.

Example

curl https://launchalways.com/api/v1/email-verifications/b7e4f7a3-0000-4000-9000-123456789abc \
  -H "Authorization: Bearer la_your_api_key_here"

Success Response

{
  "emailId": "b7e4f7a3-0000-4000-9000-123456789abc",
  "email": "user@example.com",
  "expiresInMs": 300000,
  "language": "en",
  "status": "sent",
  "expiresAt": "2026-06-08T12:34:56.789Z",
  "createdAt": "2026-06-08T12:29:56.789Z"
}

Success Response Fields

Field	Type	Required	Nullable	Constraints	Description
`emailId`	uuid	Yes	No	UUID string	Sent email record ID.
`email`	string	Yes	No	Normalized email address	Recipient email address.
`expiresInMs`	number \| null	Yes	Yes	Integer, 1000-86400000 when available	Validity window originally submitted to the send endpoint.
`language`	string	Yes	No	One of the supported language enum values	Language that was used to render the sent email.
`status`	`sent` \| `expired`	Yes	No	Enum: sent, expired	sent before the expiry time, expired after the expiry time.
`expiresAt`	ISO datetime	Yes	No	ISO 8601 timestamp	Absolute expiration time for the code in this email.
`createdAt`	ISO datetime	Yes	No	ISO 8601 timestamp	When LaunchAlways created the sent email record.

Error Responses

Status	Body	When it happens
`401`	`{"error":"Invalid or missing API key."}`	Missing, malformed, or unknown Bearer token.
`404`	`{"error":"Email record not found."}`	The lookup ID is invalid, missing, or belongs to another project.
`500`	`{"error":"Could not load email record."}`	The record exists but could not be loaded because of a server error.

security

Security Notes

API keys and verification checks should only be called from trusted server environments. LaunchAlways stores verification codes as non-reversible hashes with a server-side pepper.

data_object

Standard Error Object

Error responses listed above use this JSON object shape.

{
  "error": "Invalid or missing API key."
}

Field	Type	Required	Nullable	Constraints	Description
`error`	string	Yes	No	Human-readable message	Explains why the request failed.