Test Email Connection

Check a mailbox's SMTP and IMAP login without saving anything.

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

Requires an API key with the write scope.

FoxReach connects to the mail servers you name and tries the login, then reports each result. Nothing is saved. The password is sent to the mail provider only; it is never stored, logged or returned. The write scope is needed because the call makes FoxReach connect out with your credentials.

The SMTP login is tested on ports 465 and 587. On any other port only the connection and greeting are checked. IMAP is tested with a login and opening the inbox read-only.

The hosts must resolve to public mail servers. A host that is, or resolves to, a private, loopback or link-local address is refused without connecting, and both results come back as failed with a message saying so.

Body Parameters#

emailstringbodyrequired

The mailbox address.

passwordstringbodyrequired

The mailbox password or app password.

smtpHoststringbodyrequired

SMTP server, for example smtp.gmail.com.

smtpPortintegerbody

SMTP port. Default 587.

imapHoststringbodyrequired

IMAP server, for example imap.gmail.com.

imapPortintegerbody

IMAP port. Default 993.

Response#

dataobject

Show data

smtpSuccessboolean

Whether the SMTP connection (and login, on 465 and 587) worked.

smtpErrorstring

The error, or null.

imapSuccessboolean

Whether the IMAP login and inbox open worked.

imapErrorstring

The error, or null.

Errors#

Status	Description
`401`	Missing, invalid, revoked or expired API key
`403`	API key does not have the required scope: `write`
`422`	`email` is not an address, or a required field is missing

Rate Limit#

100 requests per minute, shared by every expensive call in your workspace. Fixed 60-second window.
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch seconds) and X-RateLimit-Bucket (expensive).
A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns, see Rate Limiting.

Request

cURL

curl -X POST "https://api.foxreach.io/api/v1/email-accounts/test" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "sales@acme.com", "password": "app-password", "smtpHost": "smtp.gmail.com", "imapHost": "imap.gmail.com"}'

Python SDK

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
result = client.email_accounts.test_connection(
    "sales@acme.com", "app-password", smtp_host="smtp.gmail.com", imap_host="imap.gmail.com",
)

TypeScript SDK

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const result = await client.emailAccounts.testConnection({
  email: "sales@acme.com", password: "app-password",
  smtpHost: "smtp.gmail.com", imapHost: "imap.gmail.com",
});

Response

JSON

{
  "data": {"smtpSuccess": true, "smtpError": null, "imapSuccess": false, "imapError": "IMAP error: [AUTHENTICATIONFAILED] Invalid credentials"}
}

Was this page helpful?

View as MarkdownLast updated November 4, 2026