Add SMTP Mailboxes

Connect SMTP mailboxes you already own and start their warmup. Send 1 to 10 mailboxes per request.

How each mailbox is handled

The mailbox must sign in to its mail server before anything is charged. A mailbox that cannot sign in is not kept.

When it signs in, warmup starts and the first month is charged to your wallet, at the price shown by Get Warmup Pricing.

Before any mailbox is checked, your wallet must cover all the new mailboxes in the request. Otherwise the whole request is refused with 400 and nothing is charged.

Passwords are stored encrypted and are never returned by the API.

The server must be reachable on the public internet: use a host name, not an IP address. SMTP ports 25, 465, 587 and 2525 and IMAP ports 143 and 993 are accepted.

Mailboxes you already connected

A mailbox already connected in this workspace is skipped with already_connected, and its UIDs are returned. Nothing is charged and nothing changes. To replace its sign-in details, send update_existing: true. If the mailbox's warmup is running, the new details are tested first, saved only if they work, and warmup restarts from day one. If it has no warmup running, the details are saved and checked when warmup starts again. Updating is never charged. To start warmup again for a mailbox whose warmup you cancelled, send its ext_mbx_ UID to Add Warmup to Mailboxes.

How the response works

If the request is invalid, it is refused with 400 and no mailbox is changed.

Otherwise the response is 200 and lists one result per mailbox, in the order you sent them. A request where some mailboxes fail still returns 200.

summary.total_charged is what this request charged to your wallet.

Why a mailbox can be skipped or fail

`reason`	What to do
`already_connected`	The mailbox is already connected. Use `update_existing` to replace its sign-in details.
`duplicate_in_import`	The same email appears more than once in the request. Only the first is used.
`credentials_rejected`	The mail server refused the sign-in. Check the username and password.
`server_unreachable`	The mail server could not be reached. Check the host and port.
`host_not_allowed`	The host is not allowed. Use the public host name of the mail server.
`port_not_allowed`	Use SMTP port 25, 465, 587 or 2525 and IMAP port 143 or 993.
`activation_in_progress`	Another request is adding this mailbox right now. Check again in a minute.
`insufficient_credits`	Your wallet balance ran out during the request. Add credits and send the mailbox again.
`warmup_start_failed`	Warmup could not start right now. Send the mailbox again later.

Timing and retries

A request can take up to about a minute, because every mailbox signs in to its mail server. Do not send the same mailboxes in parallel. If a request times out, wait a minute and send the same mailboxes again: mailboxes that were added are reported as already_connected and are not charged again.

If you send too many requests, or many mailboxes fail to sign in within a short time, the API answers 429. Wait for retry_after_seconds, check the sign-in details, and try again.

Once added, the mailboxes appear in List Your Connected Mailboxes, and the warmup endpoints (pause, resume, cancel, settings) work with their ext_mbx_ UIDs.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

application/json

The request was processed. Each mailbox has its own result. A request where some mailboxes fail still returns 200.

Bodyapplication/json

curl --location 'https://api.inboxkit.com/v1/api/warmup/external/smtp-mailboxes' \ --header 'X-Workspace-Id;' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "mailboxes": [ { "email": "[email protected]", "display_name": "Sam Ortiz", "smtp_host": "smtp.example.org", "smtp_port": 587, "smtp_password": "example-password-1", "imap_host": "imap.example.org", "imap_port": 993 }, { "email": "[email protected]", "display_name": "Lee Park", "smtp_host": "smtp.example.org", "smtp_port": 465, "smtp_username": "[email protected]", "smtp_password": "example-password-2" } ] }'

{ "error": false, "message": "Processed 2 mailbox(es): 2 started, 0 updated, 0 skipped, 0 failed", "results": [ { "email": "[email protected]", "status": "started", "external_mailbox_uid": "ext_mbx_2f8a6c13-9d4e-4b71-8a25-6c3e1f9d7b42", "subscription_uid": "ext_sub_8c1e5a94-3f7b-4d26-b9e0-1a6d4c8f2e57", "amount_charged": 3 }, { "email": "[email protected]", "status": "started", "external_mailbox_uid": "ext_mbx_5b3d9f27-1e6c-4a88-9d41-7f2b8e0c6a19", "subscription_uid": "ext_sub_6e2a8d15-7c4f-4b93-a1d8-3f9c5e2b7d64", "amount_charged": 3 } ], "summary": { "started": 2, "updated": 0, "failed": 0, "skipped": 0, "total_charged": 6 } }

Add SMTP Mailboxes

Request

Responses