Verify environment health
Start in the admin portal dashboard.
- Look for green checks beside the token secret, database, and queue tiles.
- Hover any warning for a one-line fix before you authorize real accounts.
- Scan the "Next Steps" list to see what work remains.
Clear this screen now so later flows stay fast and drama-free.
If multiple teammates share the same Riposte instance, coordinate who is performing OAuth flows to avoid overwriting provider credentials mid-setup.
Configure a provider integration
Pick a provider tile and copy what the UI asks for.
- Paste the redirect URI into the provider console, then bring the client ID and secret back.
- Hit "Validate" to make sure Riposte can talk to the provider right away.
- Repeat for any additional providers while the steps are fresh.
Keeping both tabs side-by-side makes the copy/paste loop painless.
Checklist
- Register the redirect URI the portal displays in your provider console
- Copy client ID and secret values exactly as provided
- Use the validation button until you see a success toast
Missing scopes are the number one cause of partial syncs. Double-check the portal's scope checklist before moving on.
Authorize a test account
Create your first auth link from the "Authenticate an account" card.
- Enter the user ID you use inside your product so everything lines up later.
- Open the generated URL in a clean browser profile and finish the OAuth flow.
- Back in the portal, confirm the account shows up as "Pending sync" or "Ready".
Using a dedicated profile keeps your personal accounts out of the test data.
If you want the same user to authorize multiple providers, reuse the user ID across each auth URL. Riposte keeps provider-specific metadata but unifies reporting by your external identifier.
Kick off and monitor syncing
Watch the activity timeline to confirm data is flowing.
- Historical sync kicks off first; realtime events follow within minutes.
- Need more detail? Call
GET /accounts/{id}to see provider state and last sync timestamps. - Large mailboxes may run in the background for a while—Riposte keeps realtime events moving in parallel.
Use the timeline filters to separate historical jobs from realtime events when debugging.
Need to adjust historical ranges or concurrency? Update riposte/sync.config.json and redeploy. Changes apply to any new accounts you onboard.
Make your first API requests
Make a quick API call to prove everything works end-to-end.
- Grab a token from the portal (or mint one via the CLI) and export it in your shell.
- Run the provided
curlsnippet forGET /messages, swapping in your user ID. - Check that the response includes the messages you expect.
Prefer an SDK? Mirror the same call in TypeScript to lock in your auth and pagination logic.
Checklist
- Generate a short-lived token in the admin portal or via the CLI
- Store the token in an environment variable before running curl
- Verify the response includes the messages you expect
Using TypeScript? Import the generated client from @riposte.co/server for typed endpoints instead of hand-writing HTTP calls.
Set up webhook delivery (optional)
Wire up realtime events once the basics are flowing.
- Create a webhook endpoint in the portal (or via
POST /webhooks/endpoints). - Point it at a tunnel like
ngrokwhile you are developing locally. - Trigger a manual sync or send a test email and watch for the delivery log.
Save one payload so you can unit test your signature verification later.
Verify the X-Riposte-Signature header before trusting the payload. Discard requests that fail validation so Riposte retries them automatically.