Client Flow Map

Client Flow Map

Purpose: define the expected top-level sequence for clients integrating with api.inbox-manager.com.

Primary Flows

1. Authenticate against auth.inbox-manager.com.
2. Resolve account context and membership.
3. Create and validate IMAP/SMTP provider credentials.
4. Sync IMAP metadata into email_messages.
5. Read message body and message parts on demand.
6. Send outbound SMTP message tasks.
7. Monitor and operate jobs (trigger/retry/resolve).
8. Use tasks for explicit queued work.
9. Review operational logs.
10. Manage subscription lifecycle actions (owner).

Endpoint Families

• Auth: /auth/*, /oauth2/*, /.well-known/jwks.json
• Accounts/members: /api/accounts*, /api/accounts/:account_id/members*
• Account context switch: POST /api/account-views/switch
• Credentials: /api/accounts/:account_id/provider-credentials*, /api/provider-credentials/:provider_credential_id/*
• Provider actions:
  • POST /api/accounts/:account_id/imap/sync-mailboxes
  • POST /api/accounts/:account_id/imap/sync-messages
  • POST /api/accounts/:account_id/smtp/messages
• Email resources:
  • /api/accounts/:account_id/emails*
  • /api/emails/:email_id
  • /api/accounts/:account_id/emails/:email_id/body
  • /api/accounts/:account_id/emails/:email_id/parts
  • /api/accounts/:account_id/emails/:email_id/parts/:part_id/content
• Tasks: /api/accounts/:account_id/tasks*, /api/tasks/:task_id*
• Jobs: /api/accounts/:account_id/jobs*, /api/jobs/:job_id*
• Logs: /api/accounts/:account_id/logs*, /api/logs/:log_id
• Subscriptions:
  • /api/subscriptions*
  • /api/subscriptions/:subscription_id/change
  • /api/subscriptions/:subscription_id/cancel
  • /api/subscriptions/stripe/checkout-session
  • /api/subscriptions/stripe/portal-session
  • /api/subscriptions/stripe/checkout-session-sync

Security Expectations

• JWT signature verification uses https://auth.inbox-manager.com/.well-known/jwks.json.
• account_id route path must match JWT account claim.
• app claim scopes all data access.
• Viewer role is read-limited and cannot fetch body or part content.
• Subscription account context comes from JWT acc claim.
• auth.inbox-manager.com and api.inbox-manager.com routes are outside this service OpenAPI.