Create Email Account

Connect a mailbox by SMTP and IMAP credentials.

POSThttps://api.foxreach.io/api/v1/email-accounts

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.

Body Parameters#

emailstringbodyrequired

The mailbox address.

passwordstringbodyrequired

The app password (or the regular password for a custom SMTP server).

providerstringbodyDefault: gmail

gmail, outlook, yahoo, zoho or custom. Sets the default SMTP and IMAP hosts and ports. An unknown value falls back to the Gmail defaults.

displayNamestringbody

Friendly name shown on sent mail.

signaturestringbody

Email signature.

smtpHoststringbody

SMTP host. Overrides the provider default. Use it with custom: the custom provider has no default host.

smtpPortintegerbody

SMTP port. Overrides the provider default (587).

imapHoststringbody

IMAP host. Overrides the provider default.

imapPortintegerbody

IMAP port. Overrides the provider default (993).

dailyLimitintegerbodyDefault: 50

Campaign emails per day, 1 to 200. Gmail and Microsoft hosts are capped at 50.

timezonestringbody

IANA timezone name. Defaults to the timezone of the user who created the API key, then UTC.

Response#

dataobject

The email account object. Passwords and OAuth tokens are never returned.

Show data

idstring

Email account identifier.

emailstring

Mailbox address.

displayNamestring

Friendly name shown on sent mail, or null.

providerstring

Provider the account was connected as.

smtpHoststring

SMTP host.

smtpPortinteger

SMTP port.

imapHoststring

IMAP host.

imapPortinteger

IMAP port.

timezonestring

IANA timezone used for the account's daily limit window.

dailyLimitinteger

Maximum campaign emails per day.

sentTodayinteger

Campaign emails sent today in the account's timezone. Warmup sends are not counted.

warmupEnabledboolean

Whether warmup is on.

warmupDailyLimitinteger

Warmup mail per day once the ramp is complete.

warmupRampUpDaysinteger

Days the warmup ramp takes.

warmupStartDatestring

ISO 8601 timestamp the ramp started, or null.

healthScoreinteger

Stored health score, or null. For the live placement score use Get Account Health.

domainAuthobject

SPF, DKIM and DMARC check result, or null until checked.

domainAuthCheckedAtstring

ISO 8601 timestamp of the last domain check, or null.

bounceRatenumber

Bounce rate.

replyRatenumber

Reply rate.

isActiveboolean

Whether the account is used for sending.

connectionStatusstring

Connection state, for example connected.

lastErrorstring

Last connection error, or null.

createdAtstring

ISO 8601 timestamp.

updatedAtstring

ISO 8601 timestamp.

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: <reason>` or `IMAP connection failed: <reason>`
`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.

Request

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"
  }'

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",
))

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",
});

Response

{
  "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"
  }
}

Was this page helpful?

View as MarkdownLast updated November 2, 2026