Provider Credentials (Features) | Inbox Manager API Documentation

Provider Credentials

The provider credentials feature defines the sign-in details used to connect your account to an email provider. It gives you a clear flow: sign in, save credentials, then use IMAP and SMTP safely.

Why This Matters

This feature keeps secret values out of standard API responses while exposing the fields clients need to operate safely. It makes validation, rotation, and deletion explicit operations so credential hygiene does not depend on side effects in sync or send flows.

Core Flow

After sign in, an authorized caller creates credential details and secret values, then validates connectivity through the test endpoint. Inbox flows reference credential IDs for IMAP and SMTP operations, and credentials are rotated or deleted explicitly as providers or security requirements change.

Operations

Operation	Endpoint	Purpose
Create credential	`POST /api/accounts/:account_id/provider-credentials`	Register account-scoped provider credential
List credentials	`GET /api/accounts/:account_id/provider-credentials`	Fetch account credential metadata
Search credentials	`POST /api/accounts/:account_id/provider-credentials/search`	Query credentials by filter
Get credential	`GET /api/provider-credentials/:provider_credential_id`	Retrieve one credential metadata record
Update credential	`PATCH /api/provider-credentials/:provider_credential_id`	Modify non-secret credential fields
Delete credential	`DELETE /api/provider-credentials/:provider_credential_id`	Remove credential from account usage
Test credential	`POST /api/provider-credentials/:provider_credential_id/test`	Run connectivity/auth validation
Rotate credential	`POST /api/provider-credentials/:provider_credential_id/rotate`	Replace active secret material

Key Data and State

{
  id: "pc_...",
  account_id: "acc_...",
  provider_kind: "imap" | "smtp",
  host: "mail.example.com",
  port: 993,
  security_mode: "ssl_tls",
  auth_kind: "password",
  username_masked: "u***@example.com"
}

Public payloads expose metadata and masked identity only.

Failure Modes and Controls

Invalid host, port, or security/auth combinations are rejected at create or update time, and test failures surface before downstream sync or send jobs execute. Secret values are excluded from read payloads, and credential rotation is explicit and auditable instead of being an implicit mutation during unrelated operations.

Provider Credential, 03-provider-credentials-and-connectivity.