Add an email address

Mails a six-digit code to the address and returns where it was sent and when the code expires. The code lives 5 minutes and allows 3 attempts; the address joins the account only when POST /v1/auth/emails/verify redeems it. Requires a recent identity confirmation. Refused when the address is already on any account, and rate limited per address.

Request

POST /v1/auth/emails

Authorization

__Host-better-auth.session_token API key · cookie required

Dashboard session cookie set at sign-in. An operation that lists only this scheme needs a person: API keys and machine credentials are refused. The same session token also works as Authorization: Bearer.

Request body

• required application/json

• email string required

  • min length 3 · max length 320

Responses

200 Response

• $schema string

  • Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.

• data object required

  • Show properties Hide properties
    • email string required
    • expiresAt string required
      • ISO 8601 timestamp for when the mailed code stops being redeemable.

default Error

Every 4xx and 5xx response is one RFC 9457 problem document served as application/problem+json.

• $schema string

  • Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.

• type string required

  • URL of the documentation page for this error. Derived from code.

• title string required

  • Human-readable name of the error type. Derived from code.

• status integer required

  • HTTP status of the response, repeated in the body.
  • min -9007199254740991 · max 9007199254740991

• detail string required

  • What went wrong in this request.

• code string required

  • Stable snake_case error code. Match on this, not on detail.

• pointer string

  • RFC 6901 JSON Pointer to the request field or batch entry that failed, for example /files/37/path. Present on validation failures.

• details object

  • Machine-readable context keyed by the error code.

• suggestions string [

  ]

  • Recovery steps safe to show to a person.

• next string [

  ]

  • Commands or API requests to run next, usable as written.

• requestId string required

  • ID of this request, from the X-Request-Id header or generated. Quote it when contacting support.

Try it

Server

• Base URL https://api.spacefast.com
• Custom base URL Overrides the selected server when set.

Authorization

• API key Remember on this device Include my values in samples

Body

• application/json

• email string *

Request Examples

cURL

curl -X POST "https://api.spacefast.com/v1/auth/emails" \
  -H "Cookie: __Host-better-auth.session_token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "string"
}'

JavaScript

const response = await fetch("https://api.spacefast.com/v1/auth/emails", {
  method: "POST",
  headers: {
    "Cookie": "__Host-better-auth.session_token=YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: "{\n  \"email\": \"string\"\n}"
});

Python

import requests

response = requests.post(
    "https://api.spacefast.com/v1/auth/emails",
    headers={
        "Cookie": "__Host-better-auth.session_token=YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    data="{\n  \"email\": \"string\"\n}",
)

Response

200 Default

{
  "$schema": "http://example.com",
  "data": {
    "email": "string",
    "expiresAt": "string"
  }
}

Error Response

{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}