Configuration File

Riposte reads all workspace-level configuration from a JSON document located at riposte/sync.config.json. The file drives both the historical sync engine and the long-lived platform services, and it is merged with the defaults defined in code every time the server boots. That means you can version-control the JSON file, override selected values per environment, and lean on environment variables for secrets.

File layout

The document supports three primary root keys:

default – Baseline sync settings shared by every environment. These map to the SyncConfig interface and control how Riposte polls, retries, and filters messages. 【F:product/src/common/config.ts†L5-L49】
environments – Optional overrides keyed by environment name. Each entry uses the same shape as default and is merged on top of it. The riposte-config CLI chooses which environment to evaluate via the --env flag, defaulting to development.
riposte – Strongly typed platform options that mirror the object returned by createRiposteServer. These map to RiposteConfig and include database settings, webhook delivery, logging, and hosted experience customization. 【F:product/src/common/strongly-typed-config.ts†L323-L377】

Additional keys are left untouched so you can keep helper metadata (for example a notes block that onboarding scripts append). They are never loaded into the live process. 【F:product/src/common/sync-config-file-validator.ts†L13-L23】【F:product/src/server/runtime-config.ts†L68-L109】

Example

{
  "default": {
    "strategies": ["webhook"],
    "batchSize": 25,
    "maxRetries": 5,
    "retryDelay": 1000,
    "rateLimitPerMinute": 120,
    "includeRead": false,
    "includeSpam": false,
    "includeTrash": false,
    "syncRange": "recent",
    "maxAge": 24
  },
  "environments": {
    "production": {
      "rateLimitPerMinute": 240,
      "strategies": ["webhook", "external"]
    }
  },
  "riposte": {
    "enabled": true,
    "database": {
      "url": "${DATABASE_URL}",
      "pool": { "max": 10 }
    },
    "notifications": {
      "default": "webhook",
      "providers": {
        "microsoft": { "mode": "polling" }
      }
    },
    "webhooks": {
      "default": {
        "url": "${WEBHOOK_URL}",
        "secret": "${WEBHOOK_SECRET}",
        "timeoutMs": 30000,
        "retryCount": 3
      }
    },
    "logging": {
      "level": "info",
      "openTelemetry": {
        "enabled": true,
        "url": "https://otel.example.com/v1/logs",
        "headers": { "x-api-key": "env:OTEL_TOKEN" }
      }
    }
  },
  "notes": {
    "generatedBy": "workspace-initializer"
  }
}

Comments are allowed (// and /* … */) and stripped before parsing, so you can annotate complex sections without breaking JSON validation. 【F:product/src/common/file-config-service.ts†L324-L411】

Referencing environment variables

Any string value can reference an environment variable by using either ${VAR_NAME} or env:VAR_NAME. Missing variables are replaced with an empty string and surfaced as warnings in the CLI. This is how you keep credentials out of source control while still seeing the complete effective config when linting. 【F:product/src/common/file-config-service.ts†L520-L608】

Sync behavior (default block)

The default and environments.* sections share the same shape. They control how the sync workers talk to provider APIs. All fields are optional—omitting a property keeps the built-in default defined in code. 【F:product/src/common/config.ts†L21-L49】

Field	Type	Description
`strategies`	`("webhook" \| "external")[]`	Delivery strategies to activate. Unknown or deprecated strategies trigger CLI warnings. 【F:product/src/common/config.ts†L5-L49】【F:product/src/common/sync-config-file-validator.ts†L30-L83】
`batchSize`	`number`	How many items the sync worker pulls per cycle. Must be > 0.
`maxRetries`	`number`	Retries for transient failures before an account is marked unhealthy. Must be ≥ 0.
`retryDelay`	`number`	Milliseconds to wait between retries. Must be ≥ 0.
`rateLimitPerMinute`	`number`	Maximum operations per minute per account. Must be > 0.
`includeRead`	`boolean`	Whether to pull read messages.
`includeSpam`	`boolean`	Whether to sync spam folders.
`includeTrash`	`boolean`	Whether to sync trash folders.
`syncRange`	`'all' \| 'recent' \| 'since' \| 'last_n_days'`	Time horizon used to seed new accounts.
`maxAge`	`number`	Hours of history to pull when `syncRange` is `recent` or `last_n_days`. Must be > 0 if provided.
`sinceDate`	ISO 8601 string	Fixed start date used when `syncRange` is `since`. Must be a valid date string.
`lastNDays`	`number`	Number of days to backfill when `syncRange` is `last_n_days`. Must be > 0.

Riposte configuration reference

Everything under the riposte key maps directly to the strongly typed configuration that powers createRiposteServer. Each section can be omitted; Riposte fills in the defaults from defaultRiposteConfig. 【F:product/src/common/strongly-typed-config.ts†L377-L548】

Global toggle

enabled (boolean) – Master switch that turns the entire service on or off. When set to false, Riposte refuses new sync jobs and provider callbacks. 【F:product/src/common/strongly-typed-config.ts†L355-L376】

Sync behavior overrides

sync (SyncBehaviorConfig) – Mirrors the fields described in the default block but applies to the live runtime (for example if you want a higher rate limit for the hosted admin portal than the baseline SDK defaults). Values inherit from defaultRiposteConfig.sync. 【F:product/src/common/strongly-typed-config.ts†L323-L346】【F:product/src/common/strongly-typed-config.ts†L377-L424】
filters (MessageFilterConfig) – Toggles for including read, spam, or trash items when the managed worker fetches mail. 【F:product/src/common/strongly-typed-config.ts†L347-L367】
range (SyncRangeConfig) – Runtime defaults for history depth. Use this to keep the hosted “connect an account” flow consistent with your workspace defaults. Validation matches the rules in the default block. 【F:product/src/common/strongly-typed-config.ts†L368-L376】【F:product/src/common/strongly-typed-config.ts†L558-L611】

Identity providers

oauth.google – Client credentials and redirect URI for Google OAuth. Defaults read from GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REDIRECT_URI. 【F:product/src/common/strongly-typed-config.ts†L388-L416】【F:product/src/common/strongly-typed-config.ts†L424-L452】
oauth.microsoft – Optional object enabling Microsoft identity. Supports tenantId in addition to the standard client credentials. Set the value to null to disable the provider even if defaults exist. 【F:product/src/common/strongly-typed-config.ts†L388-L416】【F:product/src/common/strongly-typed-config.ts†L424-L452】【F:product/src/common/strongly-typed-config.ts†L1096-L1139】

Google Cloud integrations

googleCloud.projectId – Cloud project used for Pub/Sub topics or other GCP services.
googleCloud.applicationCredentials – Path to a service account key. Often points to a file referenced via environment variable substitution.
googleCloud.pubsub – Pub/Sub delivery tuning: topic name, subscription name, batch size (maxMessages), acknowledgement deadline, and retry attempts. Defaults pull from environment variables like GOOGLE_PUBSUB_TOPIC_NAME. 【F:product/src/common/strongly-typed-config.ts†L418-L452】

Database and migrations

database – Primary persistence store for Riposte. Configure the connection string, optional write batching (batchInsert, batchSize), SSL requirements, and pool sizing via pool.{min,max,idle}. 【F:product/src/common/strongly-typed-config.ts†L454-L487】
migrations.autoApply – When true Riposte automatically applies schema migrations on boot. Disable this if you prefer running migrations during deployment. 【F:product/src/common/strongly-typed-config.ts†L489-L508】

Notifications

notifications.default – Preferred delivery channel (webhook or polling).
notifications.providers – Provider-specific overrides (for example forcing Microsoft accounts into polling while Gmail stays on webhooks).
notifications.polling – Polling cadence tuning: intervalMs, batchSize, initialLookbackMs, and maxAccountsPerCycle. Validation ensures positive numbers and known modes. 【F:product/src/common/strongly-typed-config.ts†L510-L556】【F:product/src/common/strongly-typed-config.ts†L853-L920】

Message storage

storage.imap.enabled (boolean) – Master toggle for the IMAP storage pipeline. When false, Riposte proxies IMAP traffic directly to the provider and ignores the storage tables. Set it to true to persist metadata and attachments in the unified message store. 【F:product/src/common/strongly-typed-config.ts†L416-L425】
storage.imap.persistBodies (boolean) – Controls whether Riposte stores IMAP message bodies in the database once storage is enabled. The default is false, which persists metadata and attachments while fetching bodies on demand for detail views. Enable it to return message bodies immediately at the cost of additional storage. 【F:product/src/common/strongly-typed-config.ts†L416-L425】
RIPOSTE_ENABLE_IMAP_STORAGE – Optional environment override that accepts true, 1, yes, or on to enable storage without editing the config file. Any other value disables persistence. Use primarily for per-environment overrides.
RIPOSTE_IMAP_PERSIST_BODIES – Optional environment override that accepts true, 1, yes, or on to enable body persistence without editing the config file. Any other value disables persistence. 【F:product/src/common/strongly-typed-config.ts†L1452-L1463】

Webhooks

Provide named webhook targets that Riposte can reference from jobs and CLI tasks.

webhooks – Map of identifier → configuration with the following fields:
- url, secret, headers, eventTypes – Delivery target and authentication.
- isActive – Toggle that disables dispatches without deleting the configuration.
- timeoutMs, retryCount, retryDelayMs – Fine-grained delivery controls.
- Deprecated aliases (timeout, retryDelay, retryOnFailure) are still recognized but should be migrated to the new names. 【F:product/src/common/strongly-typed-config.ts†L558-L612】【F:product/src/common/strongly-typed-config.ts†L803-L852】

External APIs

external – Optional configuration for forwarding mail events into a custom API. Set the endpoint, attach optional headers or API keys, and tune retries/timeouts. 【F:product/src/common/strongly-typed-config.ts†L614-L636】

Logging

logging.level – Minimum severity (debug, info, warn, error, or fatal).
logging.pretty – Enable human-readable formatting in development.
logging.destination – console, file, or both. When writing to disk you can set filePath, maxSize, and maxFiles for log rotation.
logging.requestLogging / performanceLogging – Toggle HTTP and performance metrics.
logging.openTelemetry – Fully managed OTLP exporter with options for target URL, headers, service metadata, queue sizing, and batch tuning. Environment variables can fill in any field. 【F:product/src/common/strongly-typed-config.ts†L638-L712】【F:product/src/common/strongly-typed-config.ts†L424-L511】【F:product/src/common/strongly-typed-config.ts†L920-L972】

Application shell

app.swaggerEnabled – Expose the OpenAPI explorer.
app.redirectUrl – Where to send users after authentication completes.
app.port / app.host – Network binding for the HTTP server.
app.adminPortal – Either false to disable the built-in portal or an object defining credentials, mount path, session secret, and optional dedicated port. Deprecated properties (adminEnabled, username, password) continue to merge for backward compatibility.
app.cors – Allowed origins and whether credentials are forwarded.
app.rateLimit – Express-rate-limit compatible window and request cap.
Legacy one-off secrets (webhookUrl, apiKey, webhookSecret, jwtSecret) are still read if present to ease migrations. 【F:product/src/common/strongly-typed-config.ts†L714-L792】【F:product/src/common/strongly-typed-config.ts†L972-L1048】

Hosted authentication screen

Customize the optional hosted OAuth experience.

authScreen.enabled – Toggle the hosted UI entirely.
authScreen.publicUrl – Canonical origin used to render links in transactional email.
authScreen.cors – CORS rules specifically for the auth UI.
authScreen.brandName, title, subtitle, supportEmail, submitButtonLabel, logoText – Marketing copy and labeling.
authScreen.layout, backgroundIllustration, theme, typography – Visual style controls.
authScreen.highlights, scopeSection, permissionDetails, footerLinks, formCopy, show* flags – Optional content blocks.
authScreen.customCssFile – Path to additional CSS loaded at runtime. 【F:product/src/auth-screen/types.ts†L1-L120】【F:product/src/auth-screen/defaults.ts†L1-L69】

Message tracking

messageTracking.enabled – Enables tracking headers or pixels.
messageTracking.headerName / pixelPath – Name of the header Riposte attaches and the pixel endpoint served to recipients.
messageTracking.defaultDomain – Named domain to use when generating public URLs.
messageTracking.domains – Map of domain key → { baseUrl, pixelPath? }. At least one domain is required when tracking is enabled. 【F:product/src/common/strongly-typed-config.ts†L794-L834】【F:product/src/common/strongly-typed-config.ts†L558-L611】【F:product/src/common/strongly-typed-config.ts†L611-L692】

Historical sync automation

historicalSync.autoStartOnConnect – Automatically trigger a historical backfill the moment an account authenticates successfully. 【F:product/src/common/strongly-typed-config.ts†L836-L848】

Notes block

The optional notes object persists arbitrary metadata for operators or automation. Riposte never reads it, but the CLI prints the content so teams can leave breadcrumbs for hand-offs. 【F:product/src/common/sync-config-file-validator.ts†L13-L23】【F:product/src/server/runtime-config.ts†L99-L109】

CLI helpers

Install dependencies in the repo root and run commands through npx or your package manager:

npm install
npx riposte-config lint --env production

Available commands:

riposte-config lint – Validates the JSON structure, resolves environment references, and prints the merged sync and Riposte configuration for the selected environment.
riposte-config explain <path> – Describes a specific configuration path (for example riposte.logging.openTelemetry).
riposte-config fields --search <term> – Lists known configuration paths and defaults, filtered by an optional search term.

Every command accepts --file to point at an alternate configuration and --env to switch environments. Use --json with lint to receive machine-readable output for CI. 【F:product/cli/config.ts†L1-L210】

API endpoints

7 endpoints

Email synchronization operations

DELETE /cursor-sync/accounts/{accountId}/config

Reset account cursor sync configuration to global defaults

Reset a specific account's cursor sync configuration to use the global defaults.

Parameters

accountId string

In path Required

Returns

Default Response

Content type: application/json

Status: 200

                
                    1
                    curl -X DELETE "http://localhost:8080/cursor-sync/accounts/{accountId}/config"

No example response available.

GET /cursor-sync/accounts/{accountId}/config

Get cursor sync configuration for an account

Retrieve the cursor-based synchronization configuration for a specific email account.

Parameters

accountId string

In path Required

Returns

Default Response

Content type: application/json

Status: 200

                
                    1
                    curl -X GET "http://localhost:8080/cursor-sync/accounts/{accountId}/config"

No example response available.

POST /cursor-sync/accounts/{accountId}/config

Configure cursor sync for an account

Set cursor-based synchronization configuration for a specific email account.

Parameters

accountId string

In path Required

Request body

Optional • application/json

Field	Type	Description	Values
`maxObjectUpdates` Optional	number	Maximum number of object updates to include in one webhook ≥ 1 • ≤ 100	—
`mode` Optional	string	Sync mode: mailbox-level or object-level notifications `mailboxobject`	—
`slidingWindowMs` Optional	number	Sliding window duration in milliseconds for batching rapid updates ≥ 100 • ≤ 30000	—

Returns

Default Response

Content type: application/json

Status: 200

                
                    1
                    curl -X POST "http://localhost:8080/cursor-sync/accounts/{accountId}/config" \
                  
                    2
                      -H "Content-Type: application/json"

No example response available.

GET /cursor-sync/accounts/configs

Get all account cursor sync configurations

Retrieve cursor sync configurations for all accounts along with the global configuration.

Parameters

This endpoint does not accept parameters.

Returns

Default Response

Content type: application/json

Status: 200

                
                    1
                    curl -X GET "http://localhost:8080/cursor-sync/accounts/configs"

No example response available.

GET /cursor-sync/global/config

Get global cursor sync configuration

Retrieve the current global default configuration for cursor-based synchronization.

Parameters

This endpoint does not accept parameters.

Returns

Default Response

Content type: application/json

Status: 200

                
                    1
                    curl -X GET "http://localhost:8080/cursor-sync/global/config"

No example response available.

POST /cursor-sync/global/config

Configure global cursor sync defaults

Set global default configuration for cursor-based synchronization across all accounts.

Parameters

This endpoint does not accept parameters.

Request body

Optional • application/json

Field	Type	Description	Values
`maxObjectUpdates` Optional	number	Default maximum number of object updates to include in one webhook ≥ 1 • ≤ 100	—
`mode` Optional	string	Default sync mode: mailbox-level or object-level notifications `mailboxobject`	—
`slidingWindowMs` Optional	number	Default sliding window duration in milliseconds for batching rapid updates ≥ 100 • ≤ 30000	—

Returns

Default Response

Content type: application/json

Status: 200

                
                    1
                    curl -X POST "http://localhost:8080/cursor-sync/global/config" \
                  
                    2
                      -H "Content-Type: application/json"

No example response available.

GET /cursor-sync/status

Get cursor sync status

Retrieve the current status of cursor-based synchronization including active sliding windows.

Parameters

This endpoint does not accept parameters.

Returns

Default Response

Content type: application/json

Status: 200

                
                    1
                    curl -X GET "http://localhost:8080/cursor-sync/status"

No example response available.