> ## Documentation Index
> Fetch the complete documentation index at: https://www.foxreach.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create, Update & Warmup

> Connect a new email account, update its settings, and manage warmup: all write paths for /api/v1/email-accounts.

These endpoints require the `write` scope (except the two health/warmup reads, which require `read`). Never returns a password, app password, or OAuth token.

## Create an account

<ParamField body="email" type="string" required>The mailbox address.</ParamField>
<ParamField body="password" type="string" required>The app password (or regular password for custom SMTP).</ParamField>
<ParamField body="provider" type="string" default="gmail">`gmail`, `outlook`, `yahoo`, `zoho`, or `custom`.</ParamField>
<ParamField body="displayName" type="string">Friendly name shown on sent mail.</ParamField>
<ParamField body="dailyLimit" type="integer" default="50">Max campaign emails per day (1-200, provider-capped).</ParamField>
<ParamField body="smtpHost" type="string">Required when provider is `custom`.</ParamField>

<ParamField body="smtpPort" type="integer" />

<ParamField body="imapHost" type="string">Required when provider is `custom`.</ParamField>

<ParamField body="imapPort" type="integer" />

```bash theme={null}
curl -X POST https://api.foxreach.io/api/v1/email-accounts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourcompany.com", "password": "app-password", "provider": "gmail"}'
```

Tests both SMTP and IMAP before saving. Returns 400 if either fails, or if the daily limit exceeds the provider-safe cap (50/day for Gmail and Microsoft 365).

## Update an account

`PATCH /api/v1/email-accounts/{id}`

<ParamField body="displayName" type="string" />

<ParamField body="dailyLimit" type="integer" />

<ParamField body="warmupEnabled" type="boolean">Flipping this off-to-on is subject to the free-plan warmed-inbox cap.</ParamField>

<ParamField body="warmupDailyLimit" type="integer" />

<ParamField body="isActive" type="boolean" />

<ParamField body="timezone" type="string" />

## Reconnect an account

`POST /api/v1/email-accounts/{id}/reconnect`

<ParamField body="password" type="string" required>The new app password to test and save.</ParamField>

Tests SMTP and IMAP against the account's stored hosts. On success, also the escape hatch for a revoked OAuth account: auth switches back to `password` and the OAuth tokens are dropped.

## Enable / disable warmup

`POST /api/v1/email-accounts/{id}/warmup/enable`
`POST /api/v1/email-accounts/{id}/warmup/disable`

No body. Enable adds the account to the shared warmup pool and resets the ramp to day 0; subject to the free-plan cap (2 warmed accounts) on an off-to-on transition. Returns 403 `upgrade_required` when the cap is hit.

## Get account health

`GET /api/v1/email-accounts/{id}/health` (read scope)

Returns `healthScore`, `healthBasis`, `bounce7d`, `warmupHealth`, `bounceRate`, `replyRate`, `sentToday`, `connectionStatus`, `warmupProgress`.

## Get warmup detail

`GET /api/v1/email-accounts/{id}/warmup` (read scope)

Returns `warmupProgress`, `poolStats` (sent/received/reply counts), and the account's last 20 warmup logs.

## Start Google sign-in

`POST /api/v1/email-accounts/google-oauth/start`

Returns `{"url": "..."}`: the Google consent URL. Open it in a browser to finish; an API key alone cannot complete an OAuth consent flow, and there is no v1 callback route (the existing browser callback is unauthenticated by design and unchanged).

## Delete an account

`DELETE /api/v1/email-accounts/{id}` - see [Delete Account](/docs/api-reference/email-accounts/delete-account). Campaign send/bounce history is kept with the account link cleared; queued sends are cancelled.