Connect an account

API referenceAccounts

From the Accounts API reference. Requests use the base URL https://app.warmerly.com/api/v1 and an API key, see Authentication.

text

POST /accounts

Connects a mailbox using manual SMTP/IMAP credentials. Requires X-Project-Id and a plan that includes the email channel, see the errors below. Fields you send that are not in the table are ignored.

Field	Type	Required	Description
`email`	string	Yes	The mailbox's email address.
`displayName`	string	No	Friendly name shown in the dashboard.
`provider`	string	Yes	One of `gmail`, `outlook`, `zoho`, `namecheap`, `custom`.
`smtp.host`	string	Yes	SMTP server hostname.
`smtp.port`	integer	Yes	SMTP server port.
`smtp.user`	string	Yes	SMTP username.
`smtp.pass`	string	Yes	SMTP password or app password. Encrypted at rest, never returned.
`imap.host`	string	Yes	IMAP server hostname.
`imap.port`	integer	Yes	IMAP server port.
`imap.user`	string	Yes	IMAP username.
`imap.pass`	string	Yes	IMAP password or app password. Encrypted at rest, never returned.
`timezone`	string	No	IANA timezone for scheduling sends. Defaults to `UTC`.

bash

curl -X POST https://app.warmerly.com/api/v1/accounts \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Project-Id: 8f14e45f-ceea-4c6a-8c8d-6b1a5b5c9c1a" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sales@yourdomain.com",
    "displayName": "Alex Carter",
    "provider": "custom",
    "smtp": { "host": "smtp.yourdomain.com", "port": 587, "user": "sales@yourdomain.com", "pass": "app-password" },
    "imap": { "host": "imap.yourdomain.com", "port": 993, "user": "sales@yourdomain.com", "pass": "app-password" },
    "timezone": "Europe/London"
  }'

Returns 201 with the created account:

json

{
  "account": {
    "id": "3a6f9e2e-4b7a-4e9a-9b1d-6e3a2f8c1a10",
    "projectId": "8f14e45f-ceea-4c6a-8c8d-6b1a5b5c9c1a",
    "kind": "real",
    "email": "sales@yourdomain.com",
    "displayName": "Alex Carter",
    "provider": "custom",
    "authMethod": "password",
    "smtpHost": "smtp.yourdomain.com",
    "smtpPort": 587,
    "smtpUser": "sales@yourdomain.com",
    "imapHost": "imap.yourdomain.com",
    "imapPort": 993,
    "imapUser": "sales@yourdomain.com",
    "timezone": "Europe/London",
    "status": "aging",
    "warmupEnabled": true,
    "warmupStartedAt": "2026-06-20T09:12:00.000Z"
  }
}

The response is the full account object (abridged above). On creation, Warmerly starts warmup (warmupStartedAt is set) and kicks off a DNS pre-flight check (SPF/DKIM/DMARC/MX) in the background; check dnsOverallStatus on a subsequent GET to see the result. Connecting an address that is already in the same project returns 409 conflict. SMTP or IMAP hosts that point at private or internal addresses are refused with 400 bad_request.

Was this page helpful?

Connect an account

More from Accounts