Warmbly Cloud for self-hosted instances

A self-hosted Warmbly instance warms mailboxes only against the other mailboxes on that same instance, which for most installs is a handful. Linking the instance to Warmbly Cloud lets those mailboxes warm in the hosted pool instead: thousands of real, monitored mailboxes exchanging natural-looking mail, with replies and inbox engagement handled for you.

Only warmup moves to the cloud. Campaigns, contacts, the unibox, tracking and every stored message stay on your server exactly as before. Linked instances also get Google and Microsoft sign-in through Warmbly's own OAuth apps, so there is no client to register: see Google and Microsoft mailboxes.

How it works

Your instance keeps a single link to a Warmbly Cloud workspace. When you enroll a mailbox, the instance sends that mailbox's SMTP/IMAP credential to the cloud, sealed in transit and at rest with the same envelope encryption the hosted product uses for every customer mailbox. From then on:

• Warmbly Cloud sends the mailbox's warmup mail, replies to partners, and rescues, opens and stars the warmup mail it receives, on Warmbly's own workers
• the cloud reads only verified warmup mail from the mailbox. Everything else that arrives is dropped unread; no history is imported and nothing is stored
• your instance stops its own warmup for that mailbox and keeps sending campaigns from it as usual
• health, daily volume and 7 day totals show up in your instance's settings as the cloud reports them

Unenrolling an SMTP/IMAP mailbox, or disconnecting the instance, deletes its credential on the cloud immediately. A mailbox that was signed in through Warmbly Cloud stays in the cloud workspace when you remove it from the instance; disconnecting the instance removes its mirrors of such mailboxes, since they cannot send without the link.

Linking your instance

The link is offered in three places on a self-hosted instance: as the last step of onboarding when you first sign in, as a banner on Mailboxes until you connect or dismiss it, and under Settings > Warmbly Cloud at any time. Whichever you use, the steps are the same:

1. Press Connect to Warmbly Cloud. The instance shows an eight character code.
2. Press Open Warmbly Cloud, or go to app.warmbly.com/connect, sign in with your Warmbly account (create one if you do not have it, it is free), enter the code and pick the workspace to link to. The workspace needs the manage settings permission.
3. Your instance notices the approval within a few seconds and moves on to mailbox selection. Switch on the mailboxes you want warmed.

The whole flow takes about a minute. A code expires after 15 minutes if nobody approves it; start again from the instance.

Google and Microsoft mailboxes: sign in through Warmbly Cloud

On a linked instance, Add account > Gmail / Google Workspace and Outlook / Microsoft 365 no longer need an OAuth client of your own. The sign-in window opens on Warmbly's verified Google and Microsoft apps, and when you approve:

• the mailbox is created in your Warmbly Cloud workspace, where its sign-in lives, and starts warming in the pool right away
• your instance gets a mirror of the mailbox with no credential on it. Campaigns, replies and the unibox work from your server as before; to send and sync, the instance asks the cloud for a short-lived access token (about an hour, cached) using its link token
• the refresh grant never leaves the cloud. Removing the mailbox from either side, unlinking the instance, or the cloud blocking the mailbox stops the instance sending from it within the hour

These mailboxes show the blue Cloud badge with "Signed in through Warmbly Cloud". The BOX_GOOGLE_* and BOX_OUTLOOK_* variables are still honoured when set, but an instance without them can now connect Google and Microsoft mailboxes as long as it is linked.

Mailboxes connected on the cloud

A Google or Microsoft mailbox you connect directly on app.warmbly.com shows up in your instance's Add account dialog under In your Warmbly Cloud workspace. Press Connect to add it to the instance the same way: the cloud keeps the sign-in, the instance sends with brokered tokens. A mailbox can be linked to one instance at a time.

Which existing mailboxes can be enrolled

Mailboxes connected with SMTP/IMAP (including Google Workspace and Microsoft 365 through an app password) can be enrolled as they are: the instance sends the credential to the cloud and keeps its own copy.

A Google or Microsoft mailbox that was signed in with your instance's own OAuth app cannot be enrolled, because that grant can only be refreshed by the app that issued it. Remove it and add it again through Warmbly Cloud to warm it there.

What your instance shows

Once linked, the Mailboxes page marks every enrolled mailbox with a blue Cloud badge, shows the cloud's daily count in the warmup column, and offers Warm in Warmbly Cloud, pause, resume and remove in each row's warmup menu. The mailbox drawer's Warmup tab shows the same block with the cloud's numbers in place of the local controls. Any member can see this; enrolling needs the manage mailboxes permission and linking needs manage settings.

Settings > Warmbly Cloud lists every active mailbox with a switch for whether it is in the pool. For enrolled mailboxes it shows the cloud's view:

Pause and resume per mailbox from the same row. Warmup settings (start volume, daily increase, ceiling, reply rate, window, days) are taken from the mailbox's own settings on your instance at enrollment time.

Free and paid tiers

Paid workspaces are always served first. Cross-tier partners are limited to mailboxes that have been healthy pool members for at least three days, so nothing unproven ever reaches a paying mailbox.

Upgrade from the link card on your instance, or from Settings > Billing on Warmbly Cloud. The workspace's regular hosted plan, if it has one, also counts as paid.

Safety and enforcement

Enrolled mailboxes are ordinary members of the hosted pool and are held to the same rules: verification tokens on every warmup message, spam placement and complaint tracking, and automatic quarantine or blocking when a mailbox starts hurting partners. A mailbox that gets quarantined on the cloud shows that state on your instance, stops being offered to partners, and re-enters on the same probation terms as any hosted mailbox.

For mailboxes signed in through Warmbly Cloud the enforcement reaches sending too. Every access token the instance draws is checked on the cloud: a mailbox the cloud has blocked, one that is no longer active there, one that was removed from the workspace, or an instance whose link was revoked gets no token, and the instance stops sending and syncing from that mailbox as soon as its cached token expires.

Unlinking

On your instance, Settings > Warmbly Cloud > Disconnect removes every enrolled mailbox from the pool, deletes their credentials on the cloud and lets local warmup take over. On Warmbly Cloud, Settings > Linked instances lists the instances linked to a workspace and can unlink any of them from the other side.

Self-hosting notes

• Traffic is outbound only: the instance calls WARMBLY_CLOUD_URL (default https://api.warmbly.com) over HTTPS. Nothing needs to reach the instance from the internet
• The instance token is stored sealed with CREDENTIALS_ENCRYPTION_KEY. Rotating that key invalidates the stored token; reconnect afterwards
• Brokered access tokens reach the worker through the backend's internal API (/api/v1/internal/cloud-link/token/:id), so workers keep needing only ENCRYPTED_KEYS_BACKEND_URL and ENCRYPTED_KEYS_WORKER_TOKEN. A worker that cannot reach the backend keeps sending from such mailboxes until its cached token expires, about an hour
• The link and the enrollment list are properties of the instance, not of a workspace, so they are not part of a workspace export. Reconnect after moving a workspace to a new instance
• INSTANCE_NAME sets the name shown on the approval page; the hostname is used when unset

Related guides

• Warmup
• Mailboxes
• Configuration reference