# Create Email Account
> Connect a mailbox by SMTP and IMAP credentials.
Requires an API key with the `write` scope.
FoxReach tests the SMTP and IMAP connection with the credentials you send before it saves anything. The password is stored encrypted and is never returned. To connect a Gmail account with Google sign-in instead, see [Start Google Sign-in](/api-reference/email-accounts/start-google-oauth).
## Body Parameters
The mailbox address.
The app password (or the regular password for a custom SMTP server).
`gmail`, `outlook`, `yahoo`, `zoho` or `custom`. Sets the default SMTP and IMAP hosts and ports. An unknown value falls back to the Gmail defaults.
Friendly name shown on sent mail.
Email signature.
SMTP host. Overrides the provider default. Use it with `custom`: the `custom` provider has no default host.
SMTP port. Overrides the provider default (587).
IMAP host. Overrides the provider default.
IMAP port. Overrides the provider default (993).
Campaign emails per day, 1 to 200. Gmail and Microsoft hosts are capped at 50.
IANA timezone name. Defaults to the timezone of the user who created the API key, then `UTC`.
## Response
The email account object. Passwords and OAuth tokens are never returned.
Email account identifier.
Mailbox address.
Friendly name shown on sent mail, or `null`.
Provider the account was connected as.
SMTP host.
SMTP port.
IMAP host.
IMAP port.
IANA timezone used for the account's daily limit window.
Maximum campaign emails per day.
Campaign emails sent today in the account's timezone. Warmup sends are not counted.
Whether warmup is on.
Warmup mail per day once the ramp is complete.
Days the warmup ramp takes.
ISO 8601 timestamp the ramp started, or `null`.
Stored health score, or `null`. For the live placement score use [Get Account Health](/api-reference/email-accounts/get-account-health).
SPF, DKIM and DMARC check result, or `null` until checked.
ISO 8601 timestamp of the last domain check, or `null`.
Bounce rate.
Reply rate.
Whether the account is used for sending.
Connection state, for example `connected`.
Last connection error, or `null`.
ISO 8601 timestamp.
ISO 8601 timestamp.
```bash cURL
curl -X POST "https://api.foxreach.io/api/v1/email-accounts" \
-H "X-API-Key: otr_your_key" \
-H "Content-Type: application/json" \
-d '{
"email": "outreach@company.com",
"password": "app-password",
"provider": "gmail",
"displayName": "John from Company"
}'
```
```python Python SDK (beta)
from foxreach import FoxReach
from foxreach.types import EmailAccountCreate
client = FoxReach(api_key="otr_your_key")
account = client.email_accounts.create(EmailAccountCreate(
email="outreach@company.com",
password="app-password",
provider="gmail",
smtp_host="smtp.gmail.com",
smtp_port=587,
imap_host="imap.gmail.com",
imap_port=993,
display_name="John from Company",
))
```
```typescript TypeScript SDK (beta)
import { FoxReach } from "foxreach";
const client = new FoxReach({ apiKey: "otr_your_key" });
const account = await client.emailAccounts.create({
email: "outreach@company.com",
password: "app-password",
provider: "gmail",
displayName: "John from Company",
});
```
```json
{
"data": {
"id": "cea_abc123",
"email": "outreach@company.com",
"displayName": "John from Company",
"provider": "gmail",
"smtpHost": "smtp.gmail.com",
"smtpPort": 587,
"imapHost": "imap.gmail.com",
"imapPort": 993,
"timezone": "UTC",
"dailyLimit": 50,
"sentToday": 0,
"warmupEnabled": false,
"warmupDailyLimit": 5,
"warmupRampUpDays": 14,
"warmupStartDate": null,
"healthScore": null,
"domainAuth": null,
"domainAuthCheckedAt": null,
"bounceRate": 0,
"replyRate": 0,
"isActive": true,
"connectionStatus": "connected",
"lastError": null,
"createdAt": "2026-10-31T10:00:00",
"updatedAt": "2026-10-31T10:00:00"
}
}
```
## Errors
| Status | Description |
|--------|-------------|
| `401` | Missing, invalid, revoked or expired API key |
| `403` | API key does not have the required scope: `write` |
| `400` | `Email account already exists` (same address in this workspace), `SMTP connection failed: ` or `IMAP connection failed: ` |
| `422` | Daily limit above the provider cap: mailboxes on Gmail and Microsoft SMTP hosts are capped at 50 campaign emails per day, or the body failed validation (invalid email, `dailyLimit` outside 1-200, unknown timezone) |
## Rate Limit
- **100 requests per minute, per API key.** Fixed 60-second window.
- Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (unix epoch seconds).
- A `429` response includes a `Retry-After` header (seconds until the bucket resets).
For client-side patterns (`Retry-After`, exponential backoff, monitoring `X-RateLimit-Remaining`), see [Rate Limiting](/rate-limiting).