# 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 <uri>
  - 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 <uri>
  - 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"
}
```