Connect an Inbox

What is an account?

In MailReach, one account = one email inbox (one unique email address). Each connected account occupies one seat for billing purposes.

Aliases are counted separately. If the same physical inbox is reachable under multiple addresses (e.g. alice@acme.com and sales@acme.com both deliver to the same mailbox), each address must be connected as its own account and each will consume its own seat. MailReach treats every email address independently. There is no concept of a shared inbox with multiple aliases.

This reflects how recipient ESPs actually evaluate senders: from their perspective, one sending address = one distinct identity. A recipient's mail provider has no visibility into how your mailboxes are structured on your side. It cannot tell that alice@acme.com and sales@acme.com land in the same physical inbox. Each address therefore builds its own sending reputation independently. Two aliases pointing to the same mailbox can have completely different deliverability outcomes, which is why each one must be warmed up and monitored on its own.

To warm up or monitor an inbox, that inbox must first be connected to your MailReach project. There are two ways to do it through the API:

IMAP/SMTP: one account at a time, using the inbox's own credentials. Works with any provider (Gmail, Outlook, custom SMTP).
Batch OAuth: connect many Gmail or Outlook accounts at once from a single workspace-level credential. Ideal for connecting dozens or hundreds of accounts programmatically.

All endpoints below are documented in full in the MailReach API reference.

Tip

If you only need an inbox for spam testing (not warming or monitoring), pass "spamchecker_only": true when connecting it. The account will not count as a warming/monitoring seat.

Option A: Connect one account via IMAP/SMTP

Use POST /v1/imap_auth with the inbox's IMAP and SMTP details:

POST https://api.mailreach.co/api/v1/imap_auth
X-Api-Key: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "email": "alice@example.com",
  "first_name": "Alice",
  "last_name": "Doe",
  "provider": "custom",

  "imap_server": "imap.example.com",
  "imap_server_port": 993,
  "imap_server_username": "alice@example.com",
  "imap_server_password": "••••••",

  "smtp_server": "smtp.example.com",
  "smtp_server_port": 587,
  "smtp_server_username": "alice@example.com",
  "smtp_server_password": "••••••",
  "smtp_server_auth_type": "plain",
  "smtp_server_starttls": true
}

Notable options:

Field	Description
`provider`	`gmail`, `outlook`, or `custom`
`test`	Set to `true` to validate credentials without saving the account. Use this before committing
`spamchecker_only`	`true` to connect the inbox for spam testing only, not warming
`id`	Include an existing account ID to update it rather than create a new one

Warning

Gmail and Outlook accounts with 2FA enabled cannot authenticate with their main password. Generate an app password from the account's security settings and use that instead.

Option B: Batch connect Gmail accounts (OAuth)

Batch connection uses an email workspace: a container that holds one set of Google service-account credentials authorized to act on behalf of many mailboxes in the same Google Workspace domain.

1. Create the workspace

POST https://api.mailreach.co/api/v1/email_workspaces
X-Api-Key: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Acme Google Workspace",
  "provider": "google",
  "file_key_json": "<contents of the service-account JSON key>"
}

The service account must have domain-wide delegation enabled for the scopes MailReach requires. See the Helpdesk for the exact configuration steps.

2. Import accounts into the workspace

POST https://api.mailreach.co/api/v1/email_workspaces/{workspace_id}/accounts
X-Api-Key: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "accounts": [
    "alice@acme.com",
    "bob@acme.com",
    "carol@acme.com"
  ]
}

Optional flags:

Field	Description
`spamchecker_only`	`true` to connect accounts for spam testing only
`imap_only` + `account_id`	Relink a single existing IMAP account to use the workspace's OAuth credentials

Option C: Batch connect Outlook / Microsoft accounts (OAuth)

Same two-step flow, using Microsoft app-registration credentials instead of a Google service account.

1. Create the workspace

POST https://api.mailreach.co/api/v1/email_workspaces
X-Api-Key: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Acme Microsoft 365",
  "provider": "outlook",
  "outlook_client_id": "••••••",
  "outlook_client_secret": "••••••",
  "outlook_client_secret_value": "••••••",
  "outlook_tenant_id": "••••••",
  "outlook_client_secret_expires_at": "31/12/2026"
}

outlook_client_secret_expires_at uses DD/MM/YYYY format. MailReach will warn you before the secret expires so you can rotate it without downtime.

2. Import accounts into the workspace

Identical to Gmail: POST /v1/email_workspaces/{workspace_id}/accounts with an accounts array of mailbox addresses from your tenant.

What happens after connecting

Once an account is connected:

It counts as one seat for warming & monitoring billing (unless spamchecker_only was set).
MailReach begins monitoring it immediately. Warming can be enabled from the account settings.
You can manage it via the /v1/accounts endpoints (reconnect, suspend, checkup, stats, and more) or in bulk via POST /v1/accounts/batch.

Next steps

One-time spam test: test inbox placement from a connected account.
Automated spam tests: schedule recurring tests from a connected sending account.
Account statistics: pull deliverability stats for connected accounts.

Automated Spam Tests

Account Statistics