Partner integration
Embed TrulyInbox warmup in your own product — you run the OAuth consent screen and keep the refresh token, and we call you back for access tokens.
Most integrations connect mailboxes by sending the owner through a TrulyInbox consent screen. A partner integration inverts that: you run your own OAuth app, your customers consent to you, and you hand us a short-lived access token per mailbox.
Everything else follows from one constraint.
The one constraint
You keep the refresh token. We never see it.
That is the whole design. It means TrulyInbox cannot mint a replacement access token when the one you gave us expires — so instead we call an endpoint you operate and ask you for a new one. Every access-token expiry, for every mailbox you connect, becomes an HTTPS request to your service.
Two consequences worth internalising before you start:
- Your refresh endpoint is on the critical path for sending. If it is down, warmup for your customers stops until it recovers.
- You must be reachable from the public internet, over TLS, from a certificate a public CA signed. Self-signed certificates fail verification.
What you build
Two endpoints, at fixed paths under a host you register:
| Method | Path | Purpose |
|---|---|---|
GET | /trulyinbox/ping | Liveness and credential check |
POST | /trulyinbox/oauth/refresh | Mint a fresh access token for one mailbox |
The paths are exact and carry no version segment. We cannot redeploy your service, so versioning the path would only be worth its confusion cost if we expected to run two contracts at once. If the contract ever changes incompatibly, it will move to a new path and your registration will record which one you speak.
Everything else you do through the ordinary Public API with an API key.
What the integration involves
Six steps, once your access is granted:
- Register your callback host — in the app, verified against your live endpoint before anything is stored.
- Build the verification endpoint —
GET /trulyinbox/ping. - Build the token-refresh endpoint —
POST /trulyinbox/oauth/refresh, the one on the critical path. - Provision a workspace per customer, each with its own daily warmup budget.
- Connect mailboxes with a live access token — the mailbox scopes are stricter than send-only, and getting them wrong is the most common failure.
- Let warmup start. Each mailbox starts warming on its own once its DNS records and a send-and-receive check pass. No enable call is needed.
The full contract for each step — request and response shapes, the exact validation we apply, the failure codes that decide retry versus suspend, and the required provider scopes — is shared once your access is approved. You will find it in the TrulyInbox app under Partner Integration in the sidebar.
Request access
Partner integration is granted per organization. Tell us what you are building and we will follow up with the full steps.