Self-hosted email delivery platform that enables applications to send emails via HTTP APIs while handling SMTP delivery, templates, storage, security, and analytics. Fully self-hostable alternative to services like SendGrid or Mailgun.
Go email-relayemail-routinghttp-to-smtpmail-deliverymailchimp-alternativemailgun-alternativemailsendermailservermailtemplatemailtestpostmark-alternativesend-emailsendgrid-alternativesendmailtransactional-emailtransactional-outbox
chore(docs): update and reorganize documentation for full feature coverage
Jonas Kanindadbc26cb731b2
diff --git a/README.md b/README.mdindex d436f96..1840779 100644--- a/README.md+++ b/README.md@@ -69,6 +69,7 @@ Response:* Attachments, custom headers, and unsubscribe support* Web view ("view in browser") with signed, expiring links* Scheduled sending and preview mode+* Email address verification (syntax, MX, disposable & role-account checks)* Async processing with Redis and Asynq* Automatic retries and priority queues@@ -111,10 +112,11 @@ Response:### Contacts & Subscribers-* Contact tracking, lists, and segmentation+* Auto-tracked contacts with per-recipient send/failure stats+* Subscriber management with static and dynamic (segmented) lists+* Bulk import via JSON or CSV with column mapping* Subscriber lifecycle (active, bounced, unsubscribed)-* Hard/soft bounce and complaint handling-* Automatic suppression lists+* Hard/soft bounce and complaint handling with automatic suppression### Unsubscribe Lists@@ -134,8 +136,9 @@ Response:### Workspaces* Multi-tenant architecture with isolated workspaces-* Role-based access control-* Shared resources and scoped API keys+* Role-based access control (owner, admin, editor, viewer)+* Member invitations and scoped API keys+* Data export/import and GDPR contact/log deletion### Webhooks & Events@@ -154,6 +157,8 @@ Response:* User and API key management* Global metrics and logs* SMTP pool management+* Usage plans with quotas and per-workspace assignment+* OAuth/SSO provider configuration* Platform configuration and retention policies### Dashboard@@ -298,5 +303,5 @@ Apache License 2.0## Copyright-Copyright (c) 2026 Jonas Kaninda and contributors+Copyright (c) 2026 Jonas Kanindadiff --git a/docs/docs/admin/plans.md b/docs/docs/admin/plans.mdindex 70daef6..e335ced 100644--- a/docs/docs/admin/plans.md+++ b/docs/docs/admin/plans.md@@ -118,3 +118,25 @@ GET /api/v1/workspaces/current/plan```Returns the effective plan and limits for the current workspace.++## User Plans++Plans can also be assigned directly to user accounts (independent of workspaces).++### Assign a Plan to a User++```+POST /api/v1/admin/users/{id}/plan+```++```json+{+ "plan_id": 2+}+```++### Get a User's Plan++```+GET /api/v1/admin/users/{id}/plan+```diff --git a/docs/docs/admin/platform-metrics.md b/docs/docs/admin/platform-metrics.mdindex 31cc54f..d0f2ca9 100644--- a/docs/docs/admin/platform-metrics.md+++ b/docs/docs/admin/platform-metrics.md@@ -6,7 +6,7 @@ description: Platform-wide metrics and analytics# Platform Metrics-Administrators can view aggregated metrics across all users.+Administrators can view aggregated metrics and analytics across all workspaces.## Overview Metrics@@ -19,19 +19,41 @@ GET /api/v1/admin/metrics"success": true,"data": {"total_users": 150,+ "total_workspaces": 200,"total_emails": 500000,- "sent": 485000,- "failed": 10000,- "bounces": 3000,- "suppressions": 1200,- "api_keys": 300+ "queued_emails": 120,+ "processing_emails": 40,+ "sent_emails": 485000,+ "failed_emails": 10000,+ "suppressed_emails": 800,+ "failure_rate": 2.0,+ "total_api_keys": 300,+ "active_api_keys": 250,+ "total_bounces": 3000,+ "total_suppressions": 1200,+ "active_workers": 4,+ "shared_smtp_servers": 3,+ "total_domains": 45,+ "total_inbound": 5000,+ "forwarded_inbound": 4800,+ "failed_inbound": 50,+ "received_inbound": 5000,+ "rejected_inbound": 150,+ "webhook_deliveries": { ... },+ "server_uptime_seconds": 86400,+ "current_goroutines": 128,+ "current_memory_usage": 52428800,+ "active_sessions": 35,+ "failed_logins_last_24h": 12,+ "two_factor_adoption_rate": 42.5,+ "two_factor_users": 64}}```## Platform Analytics-Date-filtered analytics across all users:+Date-filtered daily email counts and status breakdown across all workspaces:```GET /api/v1/admin/analytics?start_date=2026-01-01&end_date=2026-01-31@@ -45,6 +67,22 @@ GET /api/v1/admin/analytics/dashboard?start_date=2026-01-01&end_date=2026-01-31Returns delivery rate trends, bounce rate graphs, and latency percentiles.+## Provider Breakdown++```+GET /api/v1/admin/analytics/providers?start_date=2026-01-01&end_date=2026-01-31+```++Returns sent/failed counts and delivery rate grouped by recipient mailbox provider (Gmail, Outlook, etc.).++## Event Log++```+GET /api/v1/admin/events?page=1&size=20+```++Lists platform activity and system events. Supports optional category filtering via `?category=<category>`.+## Real-Time Monitoring### Event Stream (SSE)diff --git a/docs/docs/admin/platform-settings.md b/docs/docs/admin/platform-settings.mdindex 049f132..13214ec 100644--- a/docs/docs/admin/platform-settings.md+++ b/docs/docs/admin/platform-settings.md@@ -12,15 +12,53 @@ Administrators can configure platform-wide settings that affect all users via thFor the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).:::-## Available Settings+## Get Settings++```+GET /api/v1/admin/settings+```++Returns all platform settings as a list of key-value entries.++## Update Settings++Settings are updated in bulk by supplying an array of key-value pairs:-| Key | Type | Description |-|-----|------|-------------|-| `registration_enabled` | boolean | Allow new user registration |-| `email_retention_days` | integer | Days to retain email logs |-| `webhook_retention_days` | integer | Days to retain webhook delivery history |-| `audit_log_retention_days` | integer | Days to retain audit log entries |-| `bounce_handling` | string | Bounce handling configuration |-| `email_content_visible` | boolean | Show email content in logs/details |+```+PUT /api/v1/admin/settings+```++```json+{+ "settings": [+ { "key": "registration_enabled", "value": "true", "type": "bool" },+ { "key": "retention_days", "value": "60", "type": "int" }+ ]+}+```++Keys prefixed with `app.` are reserved and cannot be modified.++## Available Settings-Settings are stored as key-value pairs and can be updated in bulk.+| Key | Type | Default | Description |+|-----|------|---------|-------------|+| `registration_enabled` | bool | `false` | Allow new user self-registration |+| `require_email_verification` | bool | `true` | Require email verification on sign-up |+| `require_domain_verification` | bool | `true` | Require domain ownership verification before sending |+| `default_rate_limit_hourly` | int | `100` | Default hourly send limit for new workspaces |+| `default_rate_limit_daily` | int | `1000` | Default daily send limit for new workspaces |+| `max_batch_size` | int | `100` | Default max recipients per batch send |+| `max_attachment_size_mb` | int | `10` | Default max attachment size in MB |+| `retention_days` | int | `30` | Days to retain email logs |+| `audit_log_retention_days` | int | `90` | Days to retain audit log entries |+| `webhook_delivery_retention_days` | int | `30` | Days to retain webhook delivery history |+| `global_bounce_threshold` | int | `5` | Platform-wide bounce rate threshold (percent) |+| `smtp_timeout_seconds` | int | `30` | SMTP connection timeout in seconds |+| `maintenance_mode` | bool | `false` | Put the platform in maintenance mode |+| `allowed_signup_domains` | string | `""` | Comma-separated list of allowed sign-up email domains (empty = all) |+| `two_factor_required` | bool | `false` | Require 2FA for all users |+| `login_rate_limit_count` | int | `10` | Max login attempts per window |+| `login_rate_limit_window_minutes` | int | `15` | Rate limit window duration in minutes |+| `email_content_visibility` | bool | `false` | Show full email content (body/HTML) in logs and detail views |+| `custom_headers_enabled` | bool | `false` | Allow workspaces to add custom email headers |diff --git a/docs/docs/admin/scheduled-jobs.md b/docs/docs/admin/scheduled-jobs.mdindex f554f54..f2f7cea 100644--- a/docs/docs/admin/scheduled-jobs.md+++ b/docs/docs/admin/scheduled-jobs.md@@ -6,7 +6,7 @@ description: View and manage scheduled background jobs# Scheduled Jobs-Posta runs scheduled background jobs for maintenance tasks.+Posta runs scheduled background jobs for maintenance tasks. All times are UTC.## List Jobs@@ -21,26 +21,47 @@ Response:"success": true,"data": [{- "name": "retention_cleanup",+ "name": "account-cleanup","schedule": "0 2 * * *",- "last_execution": "2026-01-15T02:00:00Z",- "next_execution": "2026-01-16T02:00:00Z",- "status": "success"+ "running": false,+ "last_run_at": "2026-01-15T02:00:00Z",+ "last_error": "",+ "next_run_at": "2026-01-16T02:00:00Z"},{- "name": "daily_report",- "schedule": "0 8 * * *",- "last_execution": "2026-01-15T08:00:00Z",- "next_execution": "2026-01-16T08:00:00Z",- "status": "success"+ "name": "retention-cleanup",+ "schedule": "0 3 * * *",+ "running": false,+ "last_run_at": "2026-01-15T03:00:00Z",+ "last_error": "",+ "next_run_at": "2026-01-16T03:00:00Z"}]}```+Each entry includes:++| Field | Type | Description |+|-------|------|-------------|+| `name` | string | Job identifier |+| `schedule` | string | Cron expression |+| `running` | boolean | Whether the job is currently executing |+| `last_run_at` | string\|null | ISO-8601 timestamp of last execution |+| `last_error` | string | Last error message, empty if last run succeeded |+| `next_run_at` | string\|null | ISO-8601 timestamp of next scheduled run |+## Built-in Jobs| Job | Schedule | Description ||-----|----------|-------------|-| `retention_cleanup` | Daily at 2:00 AM | Deletes expired email logs, webhook deliveries, and audit entries based on retention settings |-| `daily_report` | Daily at 8:00 AM | Sends daily email summary reports to users who opted in |+| `account-cleanup` | Daily at 02:00 UTC | Permanently deletes user accounts whose scheduled deletion date has passed |+| `retention-cleanup` | Daily at 03:00 UTC | Purges expired email logs, inbound emails, webhook deliveries, audit events, and tracking data based on platform retention settings |+| `daily-report` | Daily at 07:00 UTC | Enqueues per-workspace daily summary report emails for workspace owners and admins |+| `api-key-expiry` | Daily at 08:00 UTC | Notifies workspace admins of API keys expiring within 7 days |+| `bounce-alert` | Daily at 09:00 UTC | Alerts workspace admins when their bounce rate exceeds 5% over the past 24 hours |+| `campaign-restart` | Every 5 minutes | Re-enqueues batches for campaigns that have been stuck in `sending` status for more than 10 minutes |++:::note+The cron manager is only active when the Asynq Redis queue is configured. If the queue is unavailable, no jobs run and `GET /api/v1/admin/jobs` returns an empty list.+:::diff --git a/docs/docs/admin/shared-servers.md b/docs/docs/admin/shared-servers.mdindex 7d56e4e..a020cd0 100644--- a/docs/docs/admin/shared-servers.md+++ b/docs/docs/admin/shared-servers.md@@ -1,9 +1,129 @@---sidebar_position: 4-title: Shared Servers-description: Manage shared SMTP server pool+title: Shared SMTP Servers+description: Manage the platform-wide shared SMTP server pool---# Shared SMTP Servers-See [Shared SMTP Pool](/docs/smtp-domains/shared-smtp-pool) for complete documentation on managing the shared SMTP server pool.+Administrators manage a pool of shared SMTP servers (`/api/v1/admin/servers`) that workspaces can use for delivery without configuring their own SMTP credentials. The connection is validated automatically when a server is created or updated.++:::note+For the per-workspace SMTP servers that individual workspaces own and control, see [SMTP Servers](/docs/smtp-domains/smtp-servers).+:::++## Create a Server++```+POST /api/v1/admin/servers+```++```json+{+ "name": "Primary Relay",+ "host": "smtp.example.com",+ "port": 587,+ "username": "[email protected]",+ "password": "secret",+ "encryption": "tls",+ "max_retries": 3,+ "allowed_domains": ["example.com", "company.org"],+ "security_mode": "permissive"+}+```++| Field | Required | Description |+|-------|----------|-------------|+| `name` | Yes | Display name |+| `host` | Yes | SMTP hostname |+| `port` | Yes | SMTP port (typically 25, 465, or 587) |+| `username` | No | SMTP authentication username |+| `password` | No | SMTP authentication password (stored encrypted) |+| `encryption` | No | `none`, `tls`, or `starttls` (default: `none`) |+| `max_retries` | No | Max delivery retry attempts (default: `0`) |+| `allowed_domains` | No | Restrict use to specific sender domains |+| `security_mode` | No | `permissive` or `strict` (see below) |++### Security Modes++| Mode | Description |+|------|-------------|+| `permissive` | Any workspace whose sender domain matches `allowed_domains` can use this server |+| `strict` | The workspace must have verified ownership of the sender domain via TXT record |++The SMTP connection is tested immediately on creation. If the connection fails, the server is saved with `status: invalid` and a `validation_error` message.++Returns `201 Created` on success.++## List Servers++```+GET /api/v1/admin/servers?page=1&size=20+```++## Get a Server++```+GET /api/v1/admin/servers/{id}+```++:::caution+The `password` field is never included in API responses.+:::++## Update a Server++```+PUT /api/v1/admin/servers/{id}+```++All fields are optional. If `host`, `port`, `username`, `password`, or `encryption` are changed, the connection is re-validated automatically.++To change status directly, include `"status": "enabled"` or `"status": "disabled"` in the body. Setting `status: enabled` triggers a connection re-validation before enabling.++## Delete a Server++```+DELETE /api/v1/admin/servers/{id}+```++Returns `204 No Content`.++## Enable a Server++Re-validates the connection and sets the server status to `enabled` if successful:++```+POST /api/v1/admin/servers/{id}/enable+```++If the connection test fails, the server is set to `invalid` and the response still returns `200 OK` with the updated server object.++## Disable a Server++```+POST /api/v1/admin/servers/{id}/disable+```++Immediately stops the server from being used for new deliveries.++## Test a Server++Test the SMTP connection without changing the server status:++```+POST /api/v1/admin/servers/{id}/test+```++```json+{+ "success": true,+ "data": {+ "message": "connection successful",+ "status": "enabled",+ "validated_at": "2026-05-31T10:00:00Z"+ }+}+```++If the connection fails, `success` is `false` and `message` contains the error.diff --git a/docs/docs/admin/user-management.md b/docs/docs/admin/user-management.mdindex 44680f8..e1d10cb 100644--- a/docs/docs/admin/user-management.md+++ b/docs/docs/admin/user-management.md@@ -6,7 +6,7 @@ description: Manage users from the admin panel# User Management-Administrators can create, update, and delete user accounts.+Administrators can create, update, and manage user accounts across the platform.## Create a User@@ -28,7 +28,7 @@ POST /api/v1/admin/users| `user` | Standard user — can send emails, manage own resources || `admin` | Administrator — full platform access |-Returns `409 Conflict` if the email already exists.+Returns `409 Conflict` if the email already exists. A personal workspace is automatically provisioned for the new user.## List Users@@ -39,65 +39,120 @@ GET /api/v1/admin/users?page=1&size=20## Update a User```-PUT /api/v1/admin/users/{userId}+PUT /api/v1/admin/users/{id}``````json{- "name": "Updated Name",- "email": "[email protected]",- "role": "admin"+ "role": "admin",+ "active": true,+ "email_verified": true}```+All fields are optional. Setting `active` to `false` disables the account. You cannot disable your own account.+## User MetricsGet sending statistics for a specific user:```-GET /api/v1/admin/users/{userId}/metrics+GET /api/v1/admin/users/{id}/metrics``````json{"success": true,"data": {+ "user": { ... },"total_emails": 5000,- "sent": 4850,- "failed": 100,- "bounce_rate": 1.0,- "api_keys_count": 3+ "sent_emails": 4850,+ "failed_emails": 100,+ "suppressed_emails": 50,+ "failure_rate": 2.0,+ "total_api_keys": 5,+ "active_api_keys": 3,+ "total_contacts": 1200,+ "total_bounces": 30,+ "total_suppressions": 50,+ "total_domains": 2,+ "total_smtp_servers": 1,+ "total_inbound": 100,+ "forwarded_inbound": 80,+ "failed_inbound": 5,+ "webhook_deliveries": { ... }}}```+## List User Workspaces++```+GET /api/v1/admin/users/{id}/workspaces+```++Returns all workspaces a user belongs to, including their plan information.+## Delete a User```-DELETE /api/v1/admin/users/{userId}+DELETE /api/v1/admin/users/{id}+```++Disables the account and schedules it for permanent deletion after 7 days. Returns `400 Bad Request` if deletion is already scheduled.++## Force Delete a User++```+DELETE /api/v1/admin/users/{id}/force```+Permanently deletes a user and all their data immediately. The user must be disabled (`active: false`) before this endpoint can be called.++:::caution+Force deletion is irreversible. All workspaces, emails, templates, and subscriber data owned by the user are permanently removed.+:::++## Cancel a Scheduled Deletion++```+POST /api/v1/admin/users/{id}/cancel-deletion+```++Cancels a pending account deletion and re-enables the user.+## Disable 2FA for a UserIf a user loses access to their authenticator:```-DELETE /api/v1/admin/users/{userId}/2fa+DELETE /api/v1/admin/users/{id}/2fa```-## Manage API Keys+## Revoke All Sessions-View and revoke API keys across all users:+Force a user to re-authenticate by revoking all their active sessions:```-GET /api/v1/admin/api-keys?page=1&size=20-DELETE /api/v1/admin/api-keys/{keyId}+POST /api/v1/admin/users/{id}/revoke-sessions```-## View All Emails+## User Plan++### Assign a Plan```-GET /api/v1/admin/emails?page=1&size=20+POST /api/v1/admin/users/{id}/plan```-Lists all emails across all users with pagination.+```json+{+ "plan_id": 2+}+```++### Get Effective Plan++```+GET /api/v1/admin/users/{id}/plan+```diff --git a/docs/docs/analytics/dashboard.md b/docs/docs/analytics/dashboard.mdindex 7b586f0..1e8d23d 100644--- a/docs/docs/analytics/dashboard.md+++ b/docs/docs/analytics/dashboard.md@@ -6,12 +6,18 @@ description: Dashboard statistics and metrics# Dashboard Statistics-Get an overview of your email sending activity.+Get an overview of your email sending activity. All dashboard and email listing routes are workspace-scoped and require the `X-Posta-Workspace-Id` header.-## User Dashboard Stats+## Workspace Dashboard Stats```-GET /api/v1/users/me/dashboard/stats+GET /api/v1/workspaces/current/dashboard/stats+```++```bash+curl http://localhost:9000/api/v1/workspaces/current/dashboard/stats \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"```Response:@@ -21,20 +27,42 @@ Response:"success": true,"data": {"total_emails": 15420,- "sent": 14890,- "failed": 230,- "bounce_rate": 1.5,- "delivery_rate": 96.6+ "queued_emails": 12,+ "processing_emails": 5,+ "sent_emails": 14890,+ "failed_emails": 230,+ "suppressed_emails": 40,+ "failure_rate": 1.49,+ "total_domains": 3,+ "total_smtp_servers": 2,+ "total_api_keys": 5,+ "active_api_keys": 4,+ "total_contacts": 8200,+ "total_bounces": 120,+ "total_suppressions": 40,+ "total_webhooks": 2,+ "total_inbound": 300,+ "forwarded_inbound": 280,+ "failed_inbound": 20,+ "daily_volume": [+ {"date": "2026-05-18", "sent": 800, "failed": 10},+ {"date": "2026-05-19", "sent": 950, "failed": 8}+ ],+ "webhook_deliveries": {+ "total": 500,+ "success": 490,+ "failed": 10+ }}}```## Email Listing-View your sent emails with pagination:+View sent emails for the workspace with pagination:```-GET /api/v1/users/me/emails?page=1&size=20+GET /api/v1/workspaces/current/emails?page=1&size=20```## Email Details@@ -42,7 +70,7 @@ GET /api/v1/users/me/emails?page=1&size=20Get full details for a specific email:```-GET /api/v1/users/me/emails/{emailId}+GET /api/v1/workspaces/current/emails/{id}```:::notediff --git a/docs/docs/analytics/email-analytics.md b/docs/docs/analytics/email-analytics.mdindex 6ae9510..72652e8 100644--- a/docs/docs/analytics/email-analytics.md+++ b/docs/docs/analytics/email-analytics.md@@ -6,12 +6,26 @@ description: Detailed email analytics and trends# Email Analytics-Posta provides detailed analytics on email delivery performance with date range filtering.+Posta provides detailed analytics on email delivery performance with date range filtering. All workspace analytics routes require the `X-Posta-Workspace-Id` header alongside a JWT bearer token.-## Basic Analytics+## Daily Analytics```-GET /api/v1/users/me/analytics?start_date=2026-01-01&end_date=2026-01-31&page=1&size=30+GET /api/v1/workspaces/current/analytics?from=2026-01-01&to=2026-01-31&status=sent+```++Query parameters:++| Parameter | Type | Description |+|-----------|------|-------------|+| `from` | date (YYYY-MM-DD) | Start of date range (default: 30 days ago) |+| `to` | date (YYYY-MM-DD) | End of date range (default: today) |+| `status` | string | Filter by status: `sent`, `failed`, `queued`, etc. |++```bash+curl "http://localhost:9000/api/v1/workspaces/current/analytics?from=2026-01-01&to=2026-01-31" \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"```Response:@@ -19,41 +33,127 @@ Response:```json{"success": true,- "data": [- {"date": "2026-01-01", "sent": 150, "failed": 3, "bounced": 1},- {"date": "2026-01-02", "sent": 200, "failed": 5, "bounced": 2}- ],- "pageable": {- "current_page": 1,- "size": 30,- "total_pages": 1,- "total_elements": 31+ "data": {+ "daily_counts": [+ {"date": "2026-01-01", "count": 153},+ {"date": "2026-01-02", "count": 205}+ ],+ "status_breakdown": [+ {"status": "sent", "count": 14890},+ {"status": "failed", "count": 230},+ {"status": "queued", "count": 12}+ ]}}```-## Advanced Dashboard Analytics+## Dashboard Analytics```-GET /api/v1/users/me/analytics/dashboard?start_date=2026-01-01&end_date=2026-01-31+GET /api/v1/workspaces/current/analytics/dashboard?from=2026-01-01&to=2026-01-31```Provides:-- **Delivery rate trend** — Daily delivery success rate over time-- **Bounce rate graph** — Daily bounce rate over time-- **Latency percentiles** — p50, p95, p99 email delivery latency+- **Delivery rate trends** — Daily sent/failed counts and delivery rate percentage per day+- **Bounce rate trends** — Daily hard, soft, and complaint bounce counts+- **Latency percentiles** — p50, p75, p90, p99 and average email delivery latency (seconds)++```bash+curl "http://localhost:9000/api/v1/workspaces/current/analytics/dashboard?from=2026-01-01&to=2026-01-31" \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```++Response:++```json+{+ "success": true,+ "data": {+ "delivery_rate_trends": [+ {"date": "2026-01-01", "sent": 150, "failed": 3, "total": 153, "delivery_rate": 98.04}+ ],+ "bounce_rate_trends": [+ {"date": "2026-01-01", "hard": 1, "soft": 2, "complaint": 0, "total": 3}+ ],+ "latency_percentiles": {+ "p50": 1.2,+ "p75": 2.1,+ "p90": 4.5,+ "p99": 12.3,+ "avg": 1.8+ }+ }+}+```++## Provider Breakdown++Returns sent/failed counts and delivery rate grouped by recipient mailbox provider (Gmail, Outlook, Yahoo, and others):++```+GET /api/v1/workspaces/current/analytics/providers?from=2026-01-01&to=2026-01-31+```++```bash+curl "http://localhost:9000/api/v1/workspaces/current/analytics/providers?from=2026-01-01&to=2026-01-31" \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```++Response:++```json+{+ "success": true,+ "data": {+ "providers": [+ {+ "provider": "Gmail",+ "sent": 8200,+ "failed": 80,+ "bounced": 15,+ "total": 8295,+ "delivery_rate": 99.03+ },+ {+ "provider": "Outlook",+ "sent": 3100,+ "failed": 45,+ "bounced": 8,+ "total": 3153,+ "delivery_rate": 98.57+ },+ {+ "provider": "Other",+ "sent": 3590,+ "failed": 105,+ "bounced": 17,+ "total": 3712,+ "delivery_rate": 97.15+ }+ ]+ }+}+```++Providers are sorted by total volume, descending. The `bounced` field counts suppressed emails for that provider. Results cover the requested date range and default to the last 30 days when no range is supplied.## Admin Platform AnalyticsAdministrators can view platform-wide analytics:```-GET /api/v1/admin/analytics?start_date=2026-01-01&end_date=2026-01-31+GET /api/v1/admin/analytics?from=2026-01-01&to=2026-01-31+```++```+GET /api/v1/admin/analytics/dashboard?from=2026-01-01&to=2026-01-31``````-GET /api/v1/admin/analytics/dashboard?start_date=2026-01-01&end_date=2026-01-31+GET /api/v1/admin/analytics/providers?from=2026-01-01&to=2026-01-31```-These endpoints aggregate data across all users.+These endpoints aggregate data across all workspaces and users.diff --git a/docs/docs/analytics/health-checks.md b/docs/docs/analytics/health-checks.mdindex 1b6b991..430ef39 100644--- a/docs/docs/analytics/health-checks.md+++ b/docs/docs/analytics/health-checks.md@@ -11,7 +11,7 @@ Posta provides health check endpoints for container orchestration and load balan## Liveness Probe```-GET /api/v1/healthz+GET /healthz```Returns `200 OK` if the server is running:@@ -26,7 +26,7 @@ Returns `200 OK` if the server is running:## Readiness Probe```-GET /api/v1/readyz+GET /readyz```Checks database and Redis connectivity:@@ -62,14 +62,14 @@ GET /api/v1/info```yamllivenessProbe:httpGet:- path: /api/v1/healthz+ path: /healthzport: 9000initialDelaySeconds: 5periodSeconds: 10readinessProbe:httpGet:- path: /api/v1/readyz+ path: /readyzport: 9000initialDelaySeconds: 10periodSeconds: 15@@ -79,7 +79,7 @@ readinessProbe:```yamlhealthcheck:- test: ["CMD", "curl", "-f", "http://localhost:9000/api/v1/healthz"]+ test: ["CMD", "curl", "-f", "http://localhost:9000/healthz"]interval: 30stimeout: 10sretries: 3diff --git a/docs/docs/analytics/prometheus-metrics.md b/docs/docs/analytics/prometheus-metrics.mdindex 743a659..f605d9c 100644--- a/docs/docs/analytics/prometheus-metrics.md+++ b/docs/docs/analytics/prometheus-metrics.md@@ -6,7 +6,11 @@ description: Production monitoring with Prometheus# Prometheus Metrics-Posta exposes Prometheus-compatible metrics for production monitoring when enabled.+Posta exposes Prometheus-compatible metrics for production monitoring when enabled. The metrics endpoint is served at the root path — not under `/api/v1`.++```+GET /metrics+```## Enabling Metricsdiff --git a/docs/docs/campaigns/ab-testing.md b/docs/docs/campaigns/ab-testing.mdindex 4c20d68..401d55a 100644--- a/docs/docs/campaigns/ab-testing.md+++ b/docs/docs/campaigns/ab-testing.md@@ -16,6 +16,10 @@ For the full request/response schema, see the interactive [API Reference](https:Enable A/B testing when creating a campaign:+```+POST /api/v1/workspaces/current/campaigns+```+```json{"name": "Subject Line Test",@@ -37,6 +41,14 @@ Enable A/B testing when creating a campaign:}```+```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/campaigns \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{"name":"Subject Line Test","subject":"Default subject","from_email":"[email protected]","template_id":5,"list_id":3,"ab_test_enabled":true,"ab_test_variants":[{"name":"Variant A","split_percentage":50},{"name":"Variant B","split_percentage":50}]}'+```+### Requirements- Minimum **2 variants** required@@ -59,7 +71,13 @@ When the campaign is sent, Posta randomly splits the subscriber list according tUse the campaign analytics endpoint to compare variant performance:```-GET /api/v1/users/me/campaigns/{id}/analytics+GET /api/v1/workspaces/current/campaigns/{id}/analytics+```++```bash+curl http://localhost:9000/api/v1/workspaces/current/campaigns/42/analytics \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"```The response includes delivery stats broken down by variant, allowing you to compare open rates, click rates, and other metrics across variants.@@ -69,7 +87,13 @@ The response includes delivery stats broken down by variant, allowing you to comView individual messages sent for a campaign:```-GET /api/v1/users/me/campaigns/{id}/messages?page=0&size=20+GET /api/v1/workspaces/current/campaigns/{id}/messages?page=0&size=20+```++```bash+curl "http://localhost:9000/api/v1/workspaces/current/campaigns/42/messages?page=0&size=20" \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"```Each message includes which variant was sent to that subscriber.diff --git a/docs/docs/campaigns/overview.md b/docs/docs/campaigns/overview.mdindex 087e204..ccc699e 100644--- a/docs/docs/campaigns/overview.md+++ b/docs/docs/campaigns/overview.md@@ -15,7 +15,7 @@ For the full request/response schema, see the interactive [API Reference](https:## Creating a Campaign```-POST /api/v1/users/me/campaigns+POST /api/v1/workspaces/current/campaigns``````json@@ -37,6 +37,14 @@ POST /api/v1/users/me/campaigns}```+```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/campaigns \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{"name":"April Newsletter","subject":"What'\''s new in April","from_email":"[email protected]","template_id":5,"list_id":3}'+```+### Required Fields| Field | Description |@@ -75,7 +83,7 @@ POST /api/v1/users/me/campaigns## Listing Campaigns```-GET /api/v1/users/me/campaigns?page=0&size=20+GET /api/v1/workspaces/current/campaigns?page=0&size=20```Optional query parameters:@@ -107,13 +115,13 @@ Response includes delivery stats for each campaign:## Getting a Campaign```-GET /api/v1/users/me/campaigns/{id}+GET /api/v1/workspaces/current/campaigns/{id}```## Updating a Campaign```-PUT /api/v1/users/me/campaigns/{id}+PUT /api/v1/workspaces/current/campaigns/{id}```Only `draft` campaigns can be updated. All fields are optional.@@ -121,5 +129,9 @@ Only `draft` campaigns can be updated. All fields are optional.## Deleting a Campaign```-DELETE /api/v1/users/me/campaigns/{id}+DELETE /api/v1/workspaces/current/campaigns/{id}```++:::caution+A `sending` campaign must be cancelled before it can be deleted. Cancel the campaign first, then delete it.+:::diff --git a/docs/docs/campaigns/sending.md b/docs/docs/campaigns/sending.mdindex aa4791c..60513d6 100644--- a/docs/docs/campaigns/sending.md+++ b/docs/docs/campaigns/sending.md@@ -15,7 +15,7 @@ For the full request/response schema, see the interactive [API Reference](https:## Sending a Campaign```-POST /api/v1/users/me/campaigns/{id}/send+POST /api/v1/workspaces/current/campaigns/{id}/send```No request body required. The campaign transitions from `draft` to:@@ -25,6 +25,12 @@ No request body required. The campaign transitions from `draft` to:Posta processes the subscriber list and queues individual emails for delivery. Each subscriber in the list receives one email.+```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/campaigns/42/send \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```+### Send Rate ControlIf `send_rate` is set on the campaign, Posta throttles delivery to the specified number of emails per minute. This helps avoid overwhelming SMTP servers or hitting provider rate limits.@@ -36,35 +42,59 @@ When `send_at_local_time` is `true` and `scheduled_at` is set, Posta delivers th## Pausing a Campaign```-POST /api/v1/users/me/campaigns/{id}/pause+POST /api/v1/workspaces/current/campaigns/{id}/pause```Transitions a `sending` campaign to `paused`. Emails already queued will still be delivered, but no new emails are queued.+```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/campaigns/42/pause \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```+## Resuming a Campaign```-POST /api/v1/users/me/campaigns/{id}/resume+POST /api/v1/workspaces/current/campaigns/{id}/resume```Transitions a `paused` campaign back to `sending`. Remaining subscribers will be processed.+```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/campaigns/42/resume \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```+## Cancelling a Campaign```-POST /api/v1/users/me/campaigns/{id}/cancel+POST /api/v1/workspaces/current/campaigns/{id}/cancel```Permanently cancels a campaign. Works from `sending`, `paused`, or `scheduled` states. Cancelled campaigns cannot be resumed.+```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/campaigns/42/cancel \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```+## Duplicating a Campaign```-POST /api/v1/users/me/campaigns/{id}/duplicate+POST /api/v1/workspaces/current/campaigns/{id}/duplicate```Creates a copy of the campaign with `(copy)` appended to the name. The new campaign starts in `draft` status with all settings preserved.+```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/campaigns/42/duplicate \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```+## Status Transitions```diff --git a/docs/docs/contacts/bounce-handling.md b/docs/docs/contacts/bounce-handling.mdindex 25fea59..9378c6e 100644--- a/docs/docs/contacts/bounce-handling.md+++ b/docs/docs/contacts/bounce-handling.md@@ -16,26 +16,44 @@ Posta tracks email bounces and automatically suppresses addresses that hard boun| `soft` | Temporary failure (e.g., mailbox full) | Tracked, not suppressed || `complaint` | Recipient reported as spam | Auto-suppressed |+These routes are workspace-scoped. Send a JWT plus the `X-Posta-Workspace-Id` header (a workspace-scoped API key implies the workspace).+## Record a Bounce```-POST /api/v1/users/me/bounces+POST /api/v1/workspaces/current/bounces```-```json-{- "email": "[email protected]",- "bounce_type": "hard",- "message": "550 5.1.1 The email account does not exist"-}+| Field | Required | Description |+|-------|----------|-------------|+| `email_id` | yes | UUID of the sent email this bounce relates to |+| `recipient` | yes | Bounced recipient address |+| `type` | yes | One of `hard`, `soft`, `complaint` |+| `reason` | no | Free-text diagnostic / SMTP message |++```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/bounces \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{+ "email_id": "b1e3...uuid",+ "recipient": "[email protected]",+ "type": "hard",+ "reason": "550 5.1.1 The email account does not exist"+ }'```+Returns `201 Created` with the recorded bounce. An invalid `type` returns `400`, and an unknown `email_id` returns `404`.+## List Bounces```-GET /api/v1/users/me/bounces?page=1&size=20+GET /api/v1/workspaces/current/bounces?page=0&size=20```+Each item includes `id`, `email_id`, `recipient`, `type`, `reason`, and `created_at`.+## Automatic SuppressionWhen a **hard bounce** or **complaint** is recorded:diff --git a/docs/docs/contacts/contact-lists.md b/docs/docs/contacts/contact-lists.mdindex 97de1ee..71e7b09 100644--- a/docs/docs/contacts/contact-lists.md+++ b/docs/docs/contacts/contact-lists.md@@ -1,83 +1,31 @@---sidebar_position: 2title: Contact Lists-description: Organize contacts into lists+description: Why contacts are not manually grouped, and where to manage mailing lists---# Contact Lists-Organize your contacts into reusable mailing lists.+Posta does **not** provide a "contact list" resource. [Contacts](/docs/contacts/contact-management) are auto-tracked recipients — they are created and updated by the system as you send mail, and are read-only. You cannot manually create lists of contacts or add/remove members.-## Create a List+If you are looking to group recipients, you almost certainly want one of the dedicated resources below.-```-POST /api/v1/users/me/contact-lists-```+## Reusable mailing lists → Subscriber Lists-```json-{- "name": "Newsletter Subscribers",- "description": "Users who opted in to the monthly newsletter"-}-```+To build audiences you can target with campaigns and let people subscribe to or unsubscribe from, use **Subscriber Lists**. Subscribers are first-class records (with custom attributes and subscription state), and lists can be static or dynamic (segment-based).-## List All Contact Lists+See [Subscriber Lists](/docs/subscribers/subscriber-lists) and [Subscriber Management](/docs/subscribers/subscriber-management).-```-GET /api/v1/users/me/contact-lists?page=1&size=20-```+## Opt-out groups → Unsubscribe Lists-Response includes `member_count` for each list.+To give recipients a granular way to opt out of one category of mail (for example "Product updates") without blocking everything, use **Unsubscribe Lists**. A send references an unsubscribe list so Posta can mint a one-click link that suppresses the recipient on that list only.-## Update a List+See [Unsubscribe Lists](/docs/contacts/unsubscribe-lists).-```-PUT /api/v1/users/me/contact-lists/{id}-```+## Blocking individual addresses → Suppression List-```json-{- "name": "Weekly Newsletter",- "description": "Updated description"-}-```+To stop sending to a specific address (globally or for one unsubscribe list), use the [Suppression List](/docs/contacts/suppression-list). Hard bounces and complaints add addresses here automatically.-## Delete a List--```-DELETE /api/v1/users/me/contact-lists/{id}-```--## Managing Members--### Add a Member--```-POST /api/v1/users/me/contact-lists/{listId}/members-```--```json-{- "email": "[email protected]"-}-```--Returns `409 Conflict` if the email is already a member.--### Remove a Member--```-DELETE /api/v1/users/me/contact-lists/{listId}/members-```--```json-{- "email": "[email protected]"-}-```--### List Members--```-GET /api/v1/users/me/contact-lists/{listId}/members?page=1&size=20-```+:::note+There is no `contact-lists` API. Contacts are tracked automatically; grouping and opt-out are handled by Subscriber Lists and Unsubscribe Lists.+:::diff --git a/docs/docs/contacts/contact-management.md b/docs/docs/contacts/contact-management.mdindex 4d4191a..b6817a7 100644--- a/docs/docs/contacts/contact-management.md+++ b/docs/docs/contacts/contact-management.md@@ -6,20 +6,32 @@ description: Track email recipients# Contact Management-Posta automatically tracks recipients when you send emails. You can search and view contact details from the dashboard.+Posta automatically tracks recipients when you send emails. Contacts are **read-only**: they are created and updated by the system, and the API exposes only list and detail reads — there are no create, update, or delete endpoints.++:::note+To build reusable mailing lists or manage opt-out groups, use [Subscriber Lists](/docs/subscribers/subscriber-lists) and [Unsubscribe Lists](/docs/contacts/unsubscribe-lists). Contacts are not manually grouped.+:::++These routes are workspace-scoped. Send a JWT plus the `X-Posta-Workspace-Id` header (a workspace-scoped API key implies the workspace, so the header is not needed in that case).## List Contacts```-GET /api/v1/users/me/contacts?page=1&size=20&search=alice+GET /api/v1/workspaces/current/contacts?page=0&size=20&search=alice```| Parameter | Description ||-----------|-------------|-| `page` | Page number |-| `size` | Items per page |+| `page` | Page number (zero-based, default `0`) |+| `size` | Items per page (default `20`) || `search` | Search by email or name |+```bash+curl http://localhost:9000/api/v1/workspaces/current/contacts \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```+Response:```json@@ -27,12 +39,16 @@ Response:"success": true,"data": [{+ "id": 1,+ "user_id": 1,+ "workspace_id": 1,"email": "[email protected]","name": "Alice","sent_count": 42,- "failed_count": 1,+ "fail_count": 1,"suppressed": false,- "last_sent_at": "2026-01-15T10:00:00Z"+ "last_sent_at": "2026-01-15T10:00:00Z",+ "created_at": "2026-01-01T00:00:00Z"}]}@@ -41,16 +57,16 @@ Response:## Contact Details```-GET /api/v1/users/me/contacts/{contactId}+GET /api/v1/workspaces/current/contacts/{id}```-Returns the contact with suppression status and sending statistics.+Returns a single contact by numeric ID, with the same fields as the list response. The `suppressed` flag reflects whether the contact's email is currently on the [suppression list](/docs/contacts/suppression-list).## Automatic TrackingContacts are created automatically when you send to a new email address. Posta tracks:-- **Sent count** — Total emails successfully sent-- **Failed count** — Total delivery failures-- **Suppression status** — Whether the contact is suppressed-- **Last sent** — Timestamp of the most recent email+- **`sent_count`** — Total emails successfully sent+- **`fail_count`** — Total delivery failures+- **`suppressed`** — Whether the contact's email is currently suppressed (computed at read time, not stored on the contact)+- **`last_sent_at`** — Timestamp of the most recent emaildiff --git a/docs/docs/contacts/suppression-list.md b/docs/docs/contacts/suppression-list.mdindex b15a773..f3ab445 100644--- a/docs/docs/contacts/suppression-list.md+++ b/docs/docs/contacts/suppression-list.md@@ -8,27 +8,40 @@ description: Manage suppressed email addressesThe suppression list prevents emails from being sent to specific addresses. Addresses are added automatically on hard bounces/complaints, or manually.+These routes are workspace-scoped. Send a JWT plus the `X-Posta-Workspace-Id` header (a workspace-scoped API key implies the workspace).++A suppression can be **global** (blocks all mail to the address) or **list-scoped** (an opt-out of a single [Unsubscribe List](/docs/contacts/unsubscribe-lists)). Pass `list_id` to scope a suppression to one list; omit it for a global block.+## Add to Suppression List```-POST /api/v1/users/me/suppressions+POST /api/v1/workspaces/current/suppressions```-```json-{- "email": "[email protected]",- "reason": "User requested removal"-}+| Field | Required | Description |+|-------|----------|-------------|+| `email` | yes | Address to suppress |+| `reason` | no | Free-text note |+| `list_id` | no | Scope the suppression to one unsubscribe list (omit for a global block) |++```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/suppressions \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{"email": "[email protected]", "reason": "User requested removal"}'```-Returns `409 Conflict` if already suppressed.+Manually created suppressions are stored with `kind: "manual"`. Returns `409 Conflict` if already suppressed.## List Suppressed Addresses```-GET /api/v1/users/me/suppressions?page=1&size=20+GET /api/v1/workspaces/current/suppressions?page=0&size=20&list_id=0```+Pass `list_id` (a positive integer) to return only suppressions scoped to that unsubscribe list. Omit it (or use `0`) to list all.+Response:```json@@ -36,8 +49,12 @@ Response:"success": true,"data": [{- "id": "uuid",+ "id": 1,+ "user_id": 1,+ "workspace_id": 1,"email": "[email protected]",+ "list_id": null,+ "kind": "manual","reason": "User requested removal","created_at": "2026-01-01T00:00:00Z"}@@ -45,10 +62,12 @@ Response:}```+The `kind` field classifies why an address is suppressed: `hard`, `bounce`, `complaint`, `list_unsubscribe`, or `manual`.+## Remove from Suppression List```-DELETE /api/v1/users/me/suppressions+DELETE /api/v1/workspaces/current/suppressions``````json@@ -57,6 +76,8 @@ DELETE /api/v1/users/me/suppressions}```+Include `list_id` to remove only the list-scoped suppression; omit it to remove the global block. Returns `204 No Content`.+## How Suppression WorksWhen sending an email:diff --git a/docs/docs/contacts/unsubscribe-lists.md b/docs/docs/contacts/unsubscribe-lists.mdnew file mode 100644index 0000000..6843203--- /dev/null+++ b/docs/docs/contacts/unsubscribe-lists.md@@ -0,0 +1,112 @@+---+sidebar_position: 5+title: Unsubscribe Lists+description: Transactional opt-out scopes for one-click unsubscribe links+---++# Unsubscribe Lists++An unsubscribe list is a **transactional opt-out scope**. A send can reference one of these by ID so Posta can mint a one-click unsubscribe link whose click suppresses the recipient on that list only — the recipient's other transactional mail (receipts, password resets) keeps flowing.++Unsubscribe lists are email-keyed and carry **no membership**: a recipient is never enrolled. The list is purely a suppression scope. This makes them distinct from [Subscriber Lists](/docs/subscribers/subscriber-lists), which are subscriber-keyed campaign audiences.++These routes are workspace-scoped. Send a JWT plus the `X-Posta-Workspace-Id` header (a workspace-scoped API key implies the workspace). Create, update, and delete require workspace edit permission.++## How it relates to sending++When a send names an unsubscribe list, the `{{ posta_unsubscribe_url }}` [system variable](/docs/templates/system-variables) renders a one-click link bound to that list and recipient. Clicking it writes a **list-scoped** [suppression](/docs/contacts/suppression-list) (`kind: "list_unsubscribe"`) for that address against this list — not a global block. Future sends that reference the same list skip the address; mail on other lists is unaffected.++## Fields++| Field | Description |+|-------|-------------|+| `id` | Numeric ID used by the authenticated API |+| `uuid` | Opaque, non-enumerable public handle (used in hosted pages / webhook payloads) |+| `name` | Internal label, unique per workspace (**required**) |+| `public_name` | Name shown to recipients on the unsubscribe page; falls back to `name` when empty |+| `description` | Optional description |+| `active` | Whether the list is active (defaults to `true`) |+| `created_at` / `updated_at` | Timestamps |++## Create an Unsubscribe List++```+POST /api/v1/workspaces/current/unsubscribe-lists+```++| Field | Required | Description |+|-------|----------|-------------|+| `name` | yes | Internal label, unique per workspace |+| `public_name` | no | Name shown to recipients |+| `description` | no | Optional description |++```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/unsubscribe-lists \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{+ "name": "product-updates",+ "public_name": "Product updates",+ "description": "Feature announcements and changelog emails"+ }'+```++New lists are created with `active: true`. Returns `201 Created`, or `409 Conflict` if a list with that name already exists in the workspace.++## List Unsubscribe Lists++```+GET /api/v1/workspaces/current/unsubscribe-lists?page=0&size=20+```++```json+{+ "success": true,+ "data": [+ {+ "id": 1,+ "uuid": "8f3c...",+ "user_id": 1,+ "workspace_id": 1,+ "name": "product-updates",+ "public_name": "Product updates",+ "description": "Feature announcements and changelog emails",+ "active": true,+ "created_at": "2026-01-01T00:00:00Z",+ "updated_at": null+ }+ ]+}+```++## Get an Unsubscribe List++```+GET /api/v1/workspaces/current/unsubscribe-lists/{id}+```++Returns the list, or `404` if it does not exist in the current workspace.++## Update an Unsubscribe List++```+PUT /api/v1/workspaces/current/unsubscribe-lists/{id}+```++All fields are optional; only the ones you send are changed. Set `active` to `false` to deactivate a list without deleting it.++```json+{+ "public_name": "Product news",+ "active": false+}+```++## Delete an Unsubscribe List++```+DELETE /api/v1/workspaces/current/unsubscribe-lists/{id}+```++Returns `204 No Content`.diff --git a/docs/docs/email-sending/email-status.md b/docs/docs/email-sending/email-status.mdindex 3ccda66..2305b5f 100644--- a/docs/docs/email-sending/email-status.md+++ b/docs/docs/email-sending/email-status.md@@ -47,7 +47,12 @@ curl http://localhost:9000/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/st## Retry Failed Emails-Failed emails can be retried from the dashboard via `POST /api/v1/users/me/emails/{emailId}/retry`.+Failed emails can be retried via `POST /api/v1/emails/{id}/retry` (API-key auth).++```bash+curl -X POST http://localhost:9000/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/retry \+ -H "Authorization: Bearer your-api-key"+```:::noteOnly emails with `failed` status can be retried. Retry respects the configured maximum retry limit.diff --git a/docs/docs/email-sending/email-verification.md b/docs/docs/email-sending/email-verification.mdnew file mode 100644index 0000000..e8e5dc2--- /dev/null+++ b/docs/docs/email-sending/email-verification.md@@ -0,0 +1,128 @@+---+sidebar_position: 7+title: Email Verification+description: Validate an email address before sending+---++# Email Verification++Check whether an email address is valid and likely deliverable before you send to it. Verification runs a series of cheap-to-expensive checks (syntax, your suppression/bounce history, disposable/role detection, and an MX lookup) and caches results to avoid repeated lookups.++```+POST /api/v1/emails/verify+```++:::tip+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).+:::++:::note+No SMTP probe is performed, so mailbox existence is never confirmed — `checks.smtp` is always reported as `"skipped"`. A `valid` result means the address is syntactically correct and the domain accepts mail, not that the specific mailbox exists.+:::++## Request++```bash+curl -X POST http://localhost:9000/api/v1/emails/verify \+ -H "Authorization: Bearer your-api-key" \+ -H "Content-Type: application/json" \+ -d '{+ "email": "[email protected]"+ }'+```++| Field | Type | Description |+|-------|------|-------------|+| `email` | string (required) | The address to verify. Validated as an email format; a syntactically malformed address is rejected with `400` before any lookup. |++### Query parameters++| Parameter | Type | Description |+|-----------|------|-------------|+| `fresh` | bool | When `true`, bypasses the cache and re-checks the address. Example: `?fresh=true`. |++## Checks performed++Verification runs the following checks in order, returning early once the verdict is conclusive:++1. **Syntax** — the address is parsed; a malformed address is conclusively `invalid`.+2. **Suppression / bounce history** (per workspace, no network) — if the address is on your suppression list or has previously hard-bounced for you, it is conclusively `invalid` for your account.+3. **Disposable detection** — the domain is matched against a known set of throwaway/disposable providers. A match short-circuits to `disposable` without a DNS lookup.+4. **Role-account detection** — the local part is matched against role addresses (e.g. `info`, `admin`, `support`); a match downgrades the verdict to `risky`.+5. **MX lookup** — the domain's mail exchangers are resolved. A domain with no MX (and no A/AAAA fallback) is `invalid`. Per RFC 5321, a domain with only an A/AAAA record is treated as having an implicit MX.++The verdict precedence is: invalid syntax → disposable → no MX → role account (risky) → valid.++## Cache behavior++- The **intrinsic** result (syntax, disposable, role, MX) is cached in Redis per address, and MX answers are cached per domain. The same address and domain are not re-checked on every call.+- The **per-workspace** flags (`suppressed`, `previously_bounced`) are always re-evaluated on each request and layered onto the (possibly cached) intrinsic result, so they reflect your current state even on a cache hit.+- `cached` is `true` in the response when the intrinsic result came from the cache.+- Pass `?fresh=true` to bypass the cache and recompute the intrinsic result.++## Response++```json+{+ "success": true,+ "data": {+ "email": "[email protected]",+ "status": "valid",+ "score": 90,+ "checks": {+ "syntax": true,+ "mx": true,+ "disposable": false,+ "role_account": false,+ "smtp": "skipped"+ },+ "reason": "",+ "mailbox_verified": false,+ "suppressed": false,+ "previously_bounced": false,+ "cached": false,+ "checked_at": "2026-05-31T12:00:00Z"+ }+}+```++| Field | Type | Description |+|-------|------|-------------|+| `email` | string | The normalized (lowercased, trimmed) address that was checked. |+| `status` | string | Overall verdict: `valid`, `invalid`, `risky`, `disposable`, or `unknown`. |+| `score` | int | Confidence score (0–100). Higher is better; e.g. `90` valid, `60` role account, `10` disposable, `0` invalid. |+| `checks` | object | Individual check outcomes (see below). |+| `reason` | string | Human-readable explanation when the address is not plainly valid. Omitted when empty. |+| `mailbox_verified` | bool | Always `false` — no SMTP RCPT probe is performed. |+| `suppressed` | bool | The address is on your workspace's suppression list. |+| `previously_bounced` | bool | The address has previously hard-bounced for your workspace. |+| `cached` | bool | Whether the intrinsic result was served from cache. |+| `checked_at` | string | Timestamp (UTC) of when the result was computed. |++### `checks` object++| Field | Type | Description |+|-------|------|-------------|+| `syntax` | bool | The address is syntactically valid. |+| `mx` | bool | The domain has resolvable MX (or A/AAAA fallback) records. |+| `disposable` | bool | The domain is a known disposable/throwaway provider. |+| `role_account` | bool | The local part is a role address (e.g. `info@`, `admin@`). |+| `smtp` | string | Always `"skipped"` — no SMTP probe is performed. |++### Status values++| Status | Meaning |+|--------|---------|+| `valid` | Syntax OK and the domain accepts mail (mailbox not probed). |+| `invalid` | Definitely undeliverable (bad syntax, no MX, suppressed, or previously bounced). |+| `risky` | Deliverable but discouraged, e.g. a role-based address. |+| `disposable` | A throwaway/disposable email provider. |+| `unknown` | Could not be determined (e.g. a transient DNS error). |++## Errors++| Status | When |+|--------|------|+| `400` | The `email` field is missing or not a valid email format. |+| `404` | Email verification is disabled on this instance. |+| `429` | The per-user hourly verification rate limit was exceeded. |diff --git a/docs/docs/email-sending/scheduled-email.md b/docs/docs/email-sending/scheduled-email.mdindex 574d79b..25d427a 100644--- a/docs/docs/email-sending/scheduled-email.md+++ b/docs/docs/email-sending/scheduled-email.md@@ -6,11 +6,15 @@ description: Schedule emails for future delivery# Scheduled Email-Send emails at a specific future time using the `send_at` field.+Send emails at a specific future time using the `send_at` field on the single-send endpoint.++```+POST /api/v1/emails/send+```## Usage-Include the `send_at` field with an ISO 8601 timestamp in the `SendEmail` request:+Include the `send_at` field with an ISO 8601 / RFC 3339 timestamp in the send request:```bashcurl -X POST http://localhost:9000/api/v1/emails/send \@@ -25,6 +29,8 @@ curl -X POST http://localhost:9000/api/v1/emails/send \}'```+The field is named `send_at` (a nullable timestamp). Use UTC (a `Z` suffix) to avoid timezone ambiguity.+## Response```json@@ -37,10 +43,34 @@ curl -X POST http://localhost:9000/api/v1/emails/send \}```-The email status will be `scheduled` until the specified time, then it transitions to `queued` and follows the normal delivery pipeline.+## How scheduling works++When `send_at` is present and in the future, Posta stores the email with status `scheduled` and records the requested delivery time on the email record (`scheduled_at`). Instead of being enqueued for immediate delivery, the email is handed to the background worker with a delay equal to the time until `send_at`.++1. The send request is validated (sender, recipients, suppression checks) exactly as a normal send.+2. The email row is persisted with status `scheduled`.+3. A delivery task is enqueued with a processing delay (`send_at - now`). The task is held by the worker queue until that time arrives.+4. When the delay elapses, the worker picks up the task, the email transitions to `processing`, and it follows the normal SMTP delivery pipeline (`sent` on success, `failed` with an `error_message` on failure).++If `send_at` is in the past (or equal to now), the email is treated as an immediate send and goes straight to `queued`.++:::note+If the scheduling enqueue fails (for example, the queue backend is unavailable), the email is marked `failed` with an `error_message` describing the failure, and the API returns an error.+:::++## Viewing scheduled emails++Track a scheduled email by its UUID using the status endpoint. It reports `scheduled` until the delivery time arrives:++```bash+curl http://localhost:9000/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/status \+ -H "Authorization: Bearer your-api-key"+```++See [Email Status](/docs/email-sending/email-status) for the full status list and response shape.## Notes-- The `send_at` time must be in the future (UTC)-- The `send_at` field is only available on the `/emails/send` endpoint-- Scheduled emails can be tracked via the [email status](/docs/email-sending/email-status) endpoint+- The `send_at` time must be in the future; otherwise the email is sent immediately.+- `send_at` is only available on the `/emails/send` endpoint (not on `/emails/send-template` or `/emails/batch`).+- There is no dedicated cancel endpoint for a scheduled email. Once accepted, the delivery task is queued for its `send_at` time.diff --git a/docs/docs/gdpr/data-deletion.md b/docs/docs/gdpr/data-deletion.mdindex cdffe07..3ea3df0 100644--- a/docs/docs/gdpr/data-deletion.md+++ b/docs/docs/gdpr/data-deletion.md@@ -6,14 +6,14 @@ description: Delete contact and email data for GDPR compliance# Data Deletion-Posta provides endpoints for GDPR-compliant data deletion.+Posta provides endpoints for GDPR-compliant data deletion scoped to the active workspace.## Delete Contact Data-Remove all data associated with a specific email address, or all contacts:+Remove all data associated with a specific email address, or all contacts in the workspace:```-POST /api/v1/users/me/gdpr/delete-contacts+POST /api/v1/workspaces/current/gdpr/delete-contacts```### Delete a Specific Contact@@ -24,36 +24,57 @@ POST /api/v1/users/me/gdpr/delete-contacts}```-### Delete All Contacts+Response:```json{- "email": null+ "success": true,+ "data": {+ "deleted": 1,+ "message": "Contact [email protected] and associated data deleted"+ }}```+This removes the contact from:+- The contacts list+- All contact list memberships+- The suppression list++### Delete All Contacts++Omit the `email` field (or pass an empty string) to delete all contacts in the workspace:++```json+{}+```+Response:```json{"success": true,"data": {- "deleted_count": 1+ "deleted": 500,+ "message": "All contacts deleted"}}```-This removes the contact from:-- The contacts list-- All contact lists-- The suppression list+```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/gdpr/delete-contacts \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{"email": "[email protected]"}'+```## Delete Email Logs-Remove email logs older than a specified number of days:+Remove email logs scoped to the active workspace, optionally filtered by age:```-POST /api/v1/users/me/gdpr/delete-email-logs+POST /api/v1/workspaces/current/gdpr/delete-email-logs```### Delete Logs Older Than 30 Days@@ -64,8 +85,22 @@ POST /api/v1/users/me/gdpr/delete-email-logs}```+Response:++```json+{+ "success": true,+ "data": {+ "deleted": 1500,+ "message": "Email logs older than 30 days deleted"+ }+}+```+### Delete All Email Logs+Pass `0` to delete all email logs regardless of age:+```json{"older_than_days": 0@@ -78,11 +113,24 @@ Response:{"success": true,"data": {- "deleted_count": 1500+ "deleted": 8200,+ "message": "All email logs deleted"}}```+:::note+Deleting email logs also removes associated bounce records.+:::++```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/gdpr/delete-email-logs \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{"older_than_days": 30}'+```+## Automatic RetentionAdministrators can configure automatic data retention via [Platform Settings](/docs/admin/platform-settings):diff --git a/docs/docs/gdpr/data-export-import.md b/docs/docs/gdpr/data-export-import.mdindex 5fd1436..2c6a699 100644--- a/docs/docs/gdpr/data-export-import.md+++ b/docs/docs/gdpr/data-export-import.md@@ -1,49 +1,76 @@---sidebar_position: 1title: Data Export & Import-description: Export and import user data+description: Export and import workspace data---# Data Export & Import-Posta supports full data export and import for GDPR compliance and environment migration.+Posta supports full workspace data export and import for GDPR compliance and environment migration.-## Export All User Data+## Export All Workspace Data```-GET /api/v1/users/me/data/export+GET /api/v1/workspaces/current/data/export```-Returns all user data as JSON:+Returns all workspace data as JSON:++```bash+curl -X GET http://localhost:9000/api/v1/workspaces/current/data/export \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+``````json{"success": true,"data": {+ "posta_version": "1.0.0",+ "exported_at": "2026-05-31T12:00:00Z",+ "workspace_settings": {+ "name": "My Workspace",+ "description": "...",+ "default_language": "en"+ },"templates": [...],"stylesheets": [...],"languages": [...],"contacts": [...],"contact_lists": [...],- "webhooks": [...],"suppressions": [...],- "settings": {...}+ "webhooks": [...],+ "smtp_servers": [...],+ "domains": [...],+ "subscribers": [...],+ "subscriber_lists": [...]}}```-## Import User Data+## Import Workspace Data```-POST /api/v1/users/me/data/import+POST /api/v1/workspaces/current/data/import+```++Send the exported JSON payload as the request body. Items are inserted; existing items are not overwritten.++```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/data/import \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d @export.json```-Send the exported JSON as the request body. Existing items are skipped (not overwritten).+Response:```json{"success": true,"data": {+ "message": "Workspace data imported successfully","imported_count": 42}}@@ -51,6 +78,6 @@ Send the exported JSON as the request body. Existing items are skipped (not over## Use Cases-- **GDPR data portability** — Users can export all their data+- **GDPR data portability** — Export all workspace data on request- **Environment migration** — Move settings between staging and production- **Backup** — Periodic data exports for disaster recoverydiff --git a/docs/docs/getting-started/configuration.md b/docs/docs/getting-started/configuration.mdindex 12bafc0..d804545 100644--- a/docs/docs/getting-started/configuration.md+++ b/docs/docs/getting-started/configuration.md@@ -13,7 +13,7 @@ Posta is configured via environment variables. All variables are prefixed with `| Variable | Default | Description ||----------|---------|-------------|| `POSTA_PORT` | `9000` | HTTP server port |-| `POSTA_ENV` | `production` | Environment name |+| `POSTA_ENV` | `dev` | Environment name || `POSTA_DEV_MODE` | `false` | Development mode — stores emails without sending || `POSTA_WEB_DIR` | `web/dist` | Path to the dashboard frontend build || `POSTA_WEB_URL` | — | Public base URL of the Posta instance |@@ -66,7 +66,7 @@ Posta is configured via environment variables. All variables are prefixed with `| Variable | Default | Description ||----------|---------|-------------|-| `POSTA_EMBEDDED_WORKER` | `true` | Run the worker within the API server process |+| `POSTA_EMBEDDED_WORKER` | `false` | Run the worker within the API server process || `POSTA_WORKER_CONCURRENCY` | `10` | Number of worker goroutines || `POSTA_WORKER_MAX_RETRIES` | `5` | Maximum retry attempts per email |diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.mdindex b839c75..e869208 100644--- a/docs/docs/getting-started/installation.md+++ b/docs/docs/getting-started/installation.md@@ -216,8 +216,8 @@ Once running, verify the deployment:```bash# Liveness probe-curl http://localhost:9000/api/v1/healthz+curl http://localhost:9000/healthz# Readiness probe (checks DB + Redis)-curl http://localhost:9000/api/v1/readyz+curl http://localhost:9000/readyz```diff --git a/docs/docs/getting-started/quickstart.md b/docs/docs/getting-started/quickstart.mdindex a1759b0..de7dfeb 100644--- a/docs/docs/getting-started/quickstart.md+++ b/docs/docs/getting-started/quickstart.md@@ -19,8 +19,9 @@ Log in to the dashboard at `http://localhost:9000` with the admin credentials coNavigate to **API Keys** and create a new key:```bash-curl -X POST http://localhost:9000/api/v1/users/me/api-keys \+curl -X POST http://localhost:9000/api/v1/workspaces/current/api-keys \-H "Authorization: Bearer <your-jwt-token>" \+ -H "X-Posta-Workspace-Id: 1" \-H "Content-Type: application/json" \-d '{"name": "my-app"}'```@@ -32,8 +33,9 @@ curl -X POST http://localhost:9000/api/v1/users/me/api-keys \Add your SMTP server:```bash-curl -X POST http://localhost:9000/api/v1/users/me/smtp-servers \+curl -X POST http://localhost:9000/api/v1/workspaces/current/smtp-servers \-H "Authorization: Bearer <your-jwt-token>" \+ -H "X-Posta-Workspace-Id: 1" \-H "Content-Type: application/json" \-d '{"host": "smtp.gmail.com",diff --git a/docs/docs/inbound/managing.md b/docs/docs/inbound/managing.mdnew file mode 100644index 0000000..1d5cbdc--- /dev/null+++ b/docs/docs/inbound/managing.md@@ -0,0 +1,132 @@+---+sidebar_position: 3+title: Managing Inbound Email+description: List, fetch, retry, export, and stream inbound email from your workspace+---++# Managing Inbound Email++These workspace-scoped endpoints let you browse and operate on received mail. All routes require a JWT and the workspace header:++```+Authorization: Bearer <jwt>+X-Posta-Workspace-Id: 1+```++## List Inbound Emails++```+GET /api/v1/workspaces/current/inbound-emails+```++Returns a paginated list scoped to the current workspace.++Query parameters:++| Param | Type | Description |+|-------|------|-------------|+| `page` | int | Page number (default `0`). |+| `size` | int | Page size (default `20`). |+| `status` | string | Filter by `received`, `forwarded`, `failed`, `rejected`, or `quarantined`. |+| `source` | string | Filter by `smtp` or `webhook`. |+| `sender` | string | Substring match on sender address (case-insensitive). |+| `q` | string | Full-text search on subject. |++```bash+curl http://localhost:9000/api/v1/workspaces/current/inbound-emails?status=received \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```++## Get an Inbound Email++```+GET /api/v1/workspaces/current/inbound-emails/{id}+```++`{id}` is the inbound email UUID. Returns the full record:++```json+{+ "id": 123,+ "uuid": "550e8400-e29b-41d4-a716-446655440000",+ "user_id": 1,+ "workspace_id": 1,+ "domain_id": 7,+ "message_id": "[email protected]",+ "sender": "[email protected]",+ "recipients": ["[email protected]"],+ "subject": "Hello",+ "text_body": "Plain text body",+ "html_body": "<p>HTML body</p>",+ "size": 2048,+ "spam_score": 0.1,+ "status": "forwarded",+ "source": "webhook",+ "retry_count": 0,+ "received_at": "2026-01-01T00:00:00Z",+ "forwarded_at": "2026-01-01T00:00:02Z",+ "created_at": "2026-01-01T00:00:00Z"+}+```++Attachment metadata and headers are stored internally (`attachments_json`, `headers_json`) and may be present when set. Fetch attachment bytes via the download endpoint below.++## Delete an Inbound Email++```+DELETE /api/v1/workspaces/current/inbound-emails/{id}+```++Removes the record and best-effort deletes its blob-stored raw message and attachments. Returns `204 No Content`.++## Retry Dispatch++```+POST /api/v1/workspaces/current/inbound-emails/{id}/retry+```++Re-enqueues a message for processing. `quarantined` records are re-run through the MIME parse pipeline; `failed` and stuck `received` records are re-dispatched to your webhook. Only `failed`, `quarantined`, or stuck `received` messages can be retried — others return `400`.++```json+{+ "id": "550e8400-e29b-41d4-a716-446655440000",+ "status": "received"+}+```++:::note+Retry requires the async worker to be running; without it the endpoint returns `403`.+:::++## Download the Raw Message++```+GET /api/v1/workspaces/current/inbound-emails/{id}/raw+```++Streams the raw RFC 5322 message as `message/rfc822` with a `.eml` filename. Returns `404` if the raw bytes were not stored.++## Download an Attachment++```+GET /api/v1/workspaces/current/inbound-emails/{uuid}/attachments/{idx}+```++Streams an attachment by zero-based index for an inbound email you own. Unlike the [public signed-token endpoint](./receiving.md#downloading-attachments-signed-token), this authenticated route needs no token. The response uses the attachment's original `Content-Type` and filename.++## Live Stream (SSE)++```+GET /api/v1/workspaces/current/inbound-stream+```++A Server-Sent Events stream of inbound-email events for the current user. Because `EventSource` cannot set headers, this endpoint authenticates with the JWT as a **query parameter** instead of the `Authorization` header.++Events emitted: `email.inbound.received`, `email.inbound.forwarded`, and `email.inbound.failed`. An initial `system.info` event is sent on connect, and the server pings every 30 seconds to keep the connection alive. Events from other users' inboxes are filtered out.++```bash+curl -N "http://localhost:9000/api/v1/workspaces/current/inbound-stream?token=<jwt>&workspace_id=1"+```++Each event's `data` carries the inbound details, including `inbound_id`, `sender`, `recipients`, `subject`, `source`, `size`, and `workspace_id`.diff --git a/docs/docs/inbound/overview.md b/docs/docs/inbound/overview.mdnew file mode 100644index 0000000..9c762fe--- /dev/null+++ b/docs/docs/inbound/overview.md@@ -0,0 +1,57 @@+---+sidebar_position: 1+title: Overview+description: Receive, store, and forward inbound email with Posta+---++# Inbound Email++Inbound email lets Posta receive messages addressed to one of your verified domains, store them, and forward them to your application. Each received message is persisted and dispatched to your workspace webhook (as the `email.inbound` event) and pushed to a live SSE stream.++## Enabling Inbound++Inbound email is off by default. Enable it with configuration:++| Variable | Default | Description |+|----------|---------|-------------|+| `POSTA_INBOUND_ENABLED` | `false` | Master switch for the inbound feature. |+| `POSTA_INBOUND_WEBHOOK_SECRET` | _(empty)_ | Opaque shared secret that authenticates the ingestion webhook. When empty, the webhook endpoint returns `403`. |+| `POSTA_INBOUND_MAX_MESSAGE_SIZE` | `26214400` (25 MiB) | Maximum raw message size in bytes. |+| `POSTA_INBOUND_MAX_ATTACH_SIZE` | `10485760` (10 MiB) | Maximum size per attachment in bytes. |++Posta also ships an SMTP listener (`POSTA_INBOUND_SMTP_*`) for receiving mail directly, but most deployments use an upstream MX provider that POSTs to the webhook endpoint documented here.++:::note+A message is only accepted if at least one recipient domain matches an ownership-verified [domain](../smtp-domains/domain-verification.md) in your account. Mail to unverified domains is rejected.+:::++## How It Works++```+provider/MX ──► POST /api/v1/inbound/webhook ──► stored (InboundEmail)+ │+ ├─► email.inbound webhook ──► your endpoint+ └─► GET /inbound-stream (SSE) ──► dashboard / app+```++1. An upstream provider (or your own MX) normalizes a message and POSTs it to `POST /api/v1/inbound/webhook`, authenticating with the opaque secret.+2. Posta resolves the recipient to a verified domain, deduplicates by message id, and persists an `InboundEmail` record (raw `.eml` and attachments go to blob storage when configured).+3. The record is dispatched asynchronously as an `email.inbound` [webhook event](../webhooks/event-types.md) to your subscribed workspace webhooks, and an `email.inbound.received` event is published to the SSE stream.+4. You can browse, retry, download, and stream inbound mail from the workspace management API.++## Statuses++An inbound email moves through these statuses:++| Status | Meaning |+|--------|---------|+| `received` | Stored, awaiting (or in) dispatch. |+| `forwarded` | Successfully dispatched to your webhook. |+| `failed` | Webhook dispatch exhausted its retries. |+| `rejected` | Refused (e.g. suppressed sender or duplicate). |+| `quarantined` | Raw message could not be parsed. |++## Next Steps++- [Receiving Email](./receiving.md) — the ingestion webhook and attachment downloads.+- [Managing Inbound Email](./managing.md) — list, fetch, retry, export, and stream from your workspace.diff --git a/docs/docs/inbound/receiving.md b/docs/docs/inbound/receiving.mdnew file mode 100644index 0000000..e88c9ab--- /dev/null+++ b/docs/docs/inbound/receiving.md@@ -0,0 +1,116 @@+---+sidebar_position: 2+title: Receiving Email+description: Ingest inbound messages via the public webhook and download attachments+---++# Receiving Email++Upstream providers (or your own MX) deliver normalized messages to Posta's public ingestion webhook. These endpoints are authenticated with the opaque inbound secret, not a JWT or API key.++## Ingestion Webhook++```+POST /api/v1/inbound/webhook+```++Authenticate with the shared secret from `POSTA_INBOUND_WEBHOOK_SECRET`, sent in the `X-Posta-Inbound-Secret` header. The comparison is constant-time. If inbound is not configured (empty secret), the endpoint returns `403`.++### Request Body++The payload is a normalized JSON envelope under a top-level `body` object:++```json+{+ "body": {+ "from": "[email protected]",+ "to": ["[email protected]"],+ "subject": "Hello",+ "text": "Plain text body",+ "html": "<p>HTML body</p>",+ "headers": { "X-Custom": "value" },+ "message_id": "<[email protected]>",+ "spam_score": 0.1,+ "attachments": [+ {+ "filename": "invoice.pdf",+ "content_type": "application/pdf",+ "content": "<base64-encoded bytes>"+ }+ ],+ "raw": "<optional base64-encoded raw RFC 5322 message>"+ }+}+```++| Field | Type | Required | Description |+|-------|------|----------|-------------|+| `from` | string | yes | Sender address. |+| `to` | array | yes | Recipient addresses. At least one must match a verified domain. |+| `subject` | string | no | Message subject. |+| `text` | string | no | Plain-text body. |+| `html` | string | no | HTML body. |+| `headers` | object | no | Map of header name to value. |+| `message_id` | string | no | RFC 5322 Message-ID; angle brackets are stripped. Used for deduplication. |+| `spam_score` | number | no | Provider-supplied spam score. |+| `attachments` | array | no | Attachments with base64-encoded `content`. |+| `raw` | string | no | Base64-encoded raw `.eml`, stored for later export. |++```bash+curl -X POST http://localhost:9000/api/v1/inbound/webhook \+ -H "X-Posta-Inbound-Secret: <inbound_secret>" \+ -H "Content-Type: application/json" \+ -d '{+ "body": {+ "from": "[email protected]",+ "to": ["[email protected]"],+ "subject": "Hello",+ "text": "Plain text body"+ }+ }'+```++### Response++On acceptance the endpoint returns `202 Accepted`:++```json+{+ "accepted": true,+ "inbound_id": "550e8400-e29b-41d4-a716-446655440000",+ "status": "received"+}+```++The `status` field and HTTP code vary by outcome:++| HTTP | `status` | Condition |+|------|----------|-----------|+| `202` | `received` | Message accepted and queued for dispatch. |+| `200` | `duplicate` | A message with the same id was already ingested (idempotent). |+| `202` | `suppressed` | Sender is on the recipient's suppression list; stored, not forwarded. |+| `403` | — | Recipient domain is not verified, or inbound is not configured. |+| `413` | `too_large` | Message or attachment exceeds the configured size limit. |+| `401` | — | Invalid inbound secret. |++### Deduplication++Posta deduplicates by `message_id` per resolved user. If no `message_id` is supplied, a stable content hash (sender, recipients, subject, and size) is used as a fallback. Re-POSTing a duplicate returns `200` with `status: "duplicate"` and the original `inbound_id`.++## Downloading Attachments (Signed Token)++When the `email.inbound` webhook is dispatched, each attachment includes a signed download URL rather than inline bytes. Webhook consumers fetch the content asynchronously:++```+GET /api/v1/inbound/attachments/{uuid}/{idx}?t={token}+```++- `{uuid}` — the inbound email UUID.+- `{idx}` — the zero-based attachment index.+- `t` — the HMAC-signed token from the webhook payload.++The token is validated against the server's HMAC key; an invalid or missing token returns `401`. The response streams the raw attachment bytes with the original `Content-Type` and a `Content-Disposition` filename.++:::note+This token-signed endpoint is for webhook consumers. Authenticated workspace users can download attachments without a token via the [management API](./managing.md#download-an-attachment).+:::diff --git a/docs/docs/sdks/java.md b/docs/docs/sdks/java.mdindex e7a125f..a94df68 100644--- a/docs/docs/sdks/java.md+++ b/docs/docs/sdks/java.md@@ -23,7 +23,7 @@ Official Java client for Posta.<dependency><groupId>com.github.goposta</groupId><artifactId>posta-java</artifactId>- <version>v0.1.0</version>+ <version>v1.1.0</version></dependency>```@@ -35,7 +35,7 @@ repositories {}dependencies {- implementation 'com.github.goposta:posta-java:v0.1.0'+ implementation 'com.github.goposta:posta-java:v1.1.0'}```@@ -44,9 +44,9 @@ dependencies {## Quick Start```java-import com.goposta.posta.PostaClient;-import com.goposta.posta.SendEmailRequest;-import com.goposta.posta.SendResponse;+import com.github.goposta.posta.PostaClient;+import com.github.goposta.posta.SendEmailRequest;+import com.github.goposta.posta.SendResponse;PostaClient client = new PostaClient("https://posta.example.com", "your-api-key");@@ -77,8 +77,8 @@ BatchResponse response = client.sendBatch(new BatchRequest().template("newsletter").from("[email protected]").recipients(List.of(- new BatchRecipient("[email protected]").templateData(Map.of("name", "Bob")),- new BatchRecipient("[email protected]").language("fr").templateData(Map.of("name", "Carol"))+ new BatchRecipient().email("[email protected]").templateData(Map.of("name", "Bob")),+ new BatchRecipient().email("[email protected]").language("fr").templateData(Map.of("name", "Carol")))));System.out.printf("Sent: %d, Failed: %d%n", response.getSent(), response.getFailed());@@ -94,14 +94,12 @@ System.out.printf("Status: %s%n", status.getStatus());## Error Handling```java-import com.goposta.posta.PostaException;+import com.github.goposta.posta.PostaException;try {client.getEmailStatus("invalid-uuid");} catch (PostaException e) {System.out.printf("Status: %d%n", e.getStatusCode());- if (e.getErrorInfo() != null) {- System.out.printf("Message: %s%n", e.getErrorInfo().getMessage());- }+ System.out.printf("Message: %s%n", e.getMessage());}```diff --git a/docs/docs/security/api-keys.md b/docs/docs/security/api-keys.mdindex 3800fd9..5b96427 100644--- a/docs/docs/security/api-keys.md+++ b/docs/docs/security/api-keys.md@@ -6,7 +6,7 @@ description: Create and manage API keys# API Keys-API keys provide programmatic access to Posta's email sending and status APIs.+API keys provide programmatic access to Posta's email sending and status APIs. Keys are scoped to a workspace and managed under `/api/v1/workspaces/current/api-keys`.:::tipFor the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).@@ -14,11 +14,47 @@ For the full request/response schema, see the interactive [API Reference](https:## Creating a Key-Create an API key from the dashboard or via `POST /api/v1/users/me/api-keys`. You can configure:+```+POST /api/v1/workspaces/current/api-keys+```++Requires a JWT bearer token and the `X-Posta-Workspace-Id` header.++```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/api-keys \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{+ "name": "Production sender",+ "allowed_ips": ["203.0.113.0/24"],+ "expires_in_days": 90+ }'+```-- **Name** — A human-readable label-- **Expiration** — Optional expiry date to enforce key rotation-- **IP allowlist** — Restrict usage to specific IPs or CIDR ranges (e.g., `203.0.113.0/24`)+Request body:++| Field | Type | Description |+|-------|------|-------------|+| `name` | string (required) | Human-readable label |+| `allowed_ips` | string[] | Restrict usage to specific IPs or CIDR ranges |+| `expires_in_days` | integer | Days until expiry; `0` or omitted means never expires |++Response (201):++```json+{+ "success": true,+ "data": {+ "key": "posta_abc123def456...",+ "id": 42,+ "name": "Production sender",+ "prefix": "posta_abc1",+ "expires_at": "2026-08-30T00:00:00Z",+ "message": "Save this key securely. It will not be shown again."+ }+}+```:::warning**Save the key immediately.** The full key is only shown once at creation time. Posta stores a hash of the key, not the key itself.@@ -26,7 +62,7 @@ Create an API key from the dashboard or via `POST /api/v1/users/me/api-keys`. Yo## Using API Keys-Include the key in the `Authorization` header:+Include the key in the `Authorization` header when sending emails or checking status:```bashcurl -X POST http://localhost:9000/api/v1/emails/send \@@ -35,15 +71,35 @@ curl -X POST http://localhost:9000/api/v1/emails/send \-d '{ ... }'```-## Managing Keys+A workspace-scoped API key already implies the workspace, so the `X-Posta-Workspace-Id` header is not needed for email-sending calls.++## Listing Keys-- **List** — View all keys (only prefix shown, never the full key)-- **Revoke** — Disable a key instantly without deleting it-- **Delete** — Permanently remove a key+```+GET /api/v1/workspaces/current/api-keys+```++Returns paginated results. The full key is never returned — only the prefix is shown for identification.++## Revoking a Key++Instantly disable a key without deleting it:++```+PUT /api/v1/workspaces/current/api-keys/{id}/revoke+```++## Deleting a Key++Permanently remove a key. Only expired or already-revoked keys can be deleted — revoke an active key first.++```+DELETE /api/v1/workspaces/current/api-keys/{id}+```## Security Features-- **Hashed storage** — Keys are stored as secure hashes with prefix for identification+- **Hashed storage** — Keys are stored as secure hashes; only the prefix is kept for identification- **Expiration** — Optional expiry dates to enforce key rotation- **IP allowlist** — Restrict keys to specific IPs or CIDR ranges- **Last used tracking** — Posta records when each key was last useddiff --git a/docs/docs/security/authentication.md b/docs/docs/security/authentication.mdindex ae5b71c..585da69 100644--- a/docs/docs/security/authentication.md+++ b/docs/docs/security/authentication.md@@ -97,7 +97,7 @@ GET /api/v1/auth/oauth/{provider}/authorizeRedirects the user to the provider's authorization page. After authentication, the provider redirects back to:```-GET /api/v1/auth/oauth/callback?code=...&state=...+GET /api/v1/auth/oauth/{provider}/callback?code=...&state=...```Posta exchanges the authorization code for user info and issues a JWT token.@@ -121,8 +121,8 @@ Authorization: Bearer posta_abc123...These endpoints do not require authentication:-- `GET /api/v1/healthz` — Liveness probe-- `GET /api/v1/readyz` — Readiness probe+- `GET /healthz` — Liveness probe+- `GET /readyz` — Readiness probe- `GET /api/v1/info` — Application info- `POST /api/v1/auth/login` — Login- `POST /api/v1/auth/register` — Registerdiff --git a/docs/docs/smtp-domains/domain-verification.md b/docs/docs/smtp-domains/domain-verification.mdindex 8777401..4d992fa 100644--- a/docs/docs/smtp-domains/domain-verification.md+++ b/docs/docs/smtp-domains/domain-verification.md@@ -11,13 +11,15 @@ Verify your sending domains to improve deliverability and prevent spoofing. Post## Register a Domain```-POST /api/v1/users/me/domains+POST /api/v1/workspaces/current/domains```-```json-{- "domain": "yourdomain.com"-}+```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/domains \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{"domain": "yourdomain.com"}'```Response:@@ -26,13 +28,35 @@ Response:{"success": true,"data": {- "id": "domain-uuid",+ "id": 1,"domain": "yourdomain.com","ownership_verified": false,- "verification_token": "posta-verify=abc123def456",- "spf_record": "v=spf1 include:yourdomain.com ~all",- "dkim_record": "...",- "dmarc_record": "v=DMARC1; p=quarantine; rua=mailto:[email protected]"+ "spf_verified": false,+ "dkim_verified": false,+ "dmarc_verified": false,+ "verification_token": "abc123def456",+ "dns_records": {+ "verification": {+ "type": "TXT",+ "host": "yourdomain.com",+ "value": "posta-verification=abc123def456"+ },+ "spf": {+ "type": "TXT",+ "host": "yourdomain.com",+ "value": "v=spf1 include:_spf.posta ~all"+ },+ "dkim": {+ "type": "CNAME",+ "host": "posta._domainkey.yourdomain.com",+ "value": "posta._domainkey.posta"+ },+ "dmarc": {+ "type": "TXT",+ "host": "_dmarc.yourdomain.com",+ "value": "v=DMARC1; p=none; rua=mailto:[email protected]"+ }+ }}}```@@ -45,32 +69,38 @@ Add the following DNS records to your domain:| Type | Host | Value ||------|------|-------|-| TXT | `@` or `yourdomain.com` | `posta-verify=abc123def456` |+| TXT | `yourdomain.com` | `posta-verification=<verification_token>` |### 2. SPF Record (TXT)| Type | Host | Value ||------|------|-------|-| TXT | `@` | `v=spf1 include:yourdomain.com ~all` |+| TXT | `yourdomain.com` | `v=spf1 include:_spf.posta ~all` |-### 3. DKIM Record (TXT)+### 3. DKIM Record (CNAME)| Type | Host | Value ||------|------|-------|-| TXT | `posta._domainkey` | *(provided in response)* |+| CNAME | `posta._domainkey.yourdomain.com` | `posta._domainkey.posta` |### 4. DMARC Record (TXT)| Type | Host | Value ||------|------|-------|-| TXT | `_dmarc` | `v=DMARC1; p=quarantine; rua=mailto:[email protected]` |+| TXT | `_dmarc.yourdomain.com` | `v=DMARC1; p=none; rua=mailto:[email protected]` |## Verify DNS RecordsAfter adding DNS records, trigger verification:```-POST /api/v1/users/me/domains/{id}/verify+POST /api/v1/workspaces/current/domains/{id}/verify+```++```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/domains/1/verify \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"```Response:@@ -79,10 +109,21 @@ Response:{"success": true,"data": {- "ownership_verified": true,- "spf_verified": true,- "dkim_verified": true,- "dmarc_verified": false+ "domain": {+ "id": 1,+ "domain": "yourdomain.com",+ "ownership_verified": true,+ "spf_verified": true,+ "dkim_verified": true,+ "dmarc_verified": false+ },+ "verification": {+ "ownership_verified": true,+ "spf_verified": true,+ "dkim_verified": true,+ "dmarc_verified": false+ },+ "fully_verified": false}}```@@ -98,11 +139,19 @@ When `require_verified_domain` is enabled in user settings, Posta will reject em## List Domains```-GET /api/v1/users/me/domains?page=1&size=20+GET /api/v1/workspaces/current/domains?page=1&size=20```+## Get Domain Details++```+GET /api/v1/workspaces/current/domains/{id}+```++The response includes the current `dns_records` values alongside the domain's verification status.+## Delete a Domain```-DELETE /api/v1/users/me/domains/{id}+DELETE /api/v1/workspaces/current/domains/{id}```diff --git a/docs/docs/smtp-domains/shared-smtp-pool.md b/docs/docs/smtp-domains/shared-smtp-pool.mdindex fa51004..88fa439 100644--- a/docs/docs/smtp-domains/shared-smtp-pool.md+++ b/docs/docs/smtp-domains/shared-smtp-pool.md@@ -20,16 +20,20 @@ POST /api/v1/admin/servers```json{+ "name": "Company Outbound","host": "smtp.company.com","port": 587,"username": "[email protected]","password": "server-password","encryption": "starttls","max_retries": 5,- "allowed_domains": ["company.com", "company.org"]+ "allowed_domains": ["company.com", "company.org"],+ "security_mode": "permissive"}```+`name` is required. `security_mode` accepts `permissive` (default) or `strict`. In strict mode, the sender must have verified ownership of the sending domain before the shared server is available to them.+### List Shared Servers```diff --git a/docs/docs/smtp-domains/smtp-servers.md b/docs/docs/smtp-domains/smtp-servers.mdindex 353c040..9ba4d2f 100644--- a/docs/docs/smtp-domains/smtp-servers.md+++ b/docs/docs/smtp-domains/smtp-servers.md@@ -14,18 +14,24 @@ For the full request/response schema, see the interactive [API Reference](https:## Adding an SMTP Server-Add a server from the dashboard or via `POST /api/v1/users/me/smtp-servers`. Example:--```json-{- "host": "smtp.gmail.com",- "port": 587,- "username": "[email protected]",- "password": "your-app-password",- "encryption": "starttls",- "max_retries": 3,- "allowed_emails": ["[email protected]", "[email protected]"]-}+```+POST /api/v1/workspaces/current/smtp-servers+```++```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/smtp-servers \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{+ "host": "smtp.gmail.com",+ "port": 587,+ "username": "[email protected]",+ "password": "your-app-password",+ "encryption": "starttls",+ "max_retries": 3,+ "allowed_emails": ["[email protected]", "[email protected]"]+ }'```### Encryption Options@@ -38,7 +44,7 @@ Add a server from the dashboard or via `POST /api/v1/users/me/smtp-servers`. Exa## Testing Connections-Verify SMTP credentials and connectivity before sending via `POST /api/v1/users/me/smtp-servers/{id}/test`. This validates the hostname, port, credentials, and encryption.+Verify SMTP credentials and connectivity before sending via `POST /api/v1/workspaces/current/smtp-servers/{id}/test`. This validates the hostname, port, credentials, and encryption.## Sender Restrictionsdiff --git a/docs/docs/subscribers/bulk-import.md b/docs/docs/subscribers/bulk-import.mdindex 7156ed1..2b71939 100644--- a/docs/docs/subscribers/bulk-import.md+++ b/docs/docs/subscribers/bulk-import.md@@ -12,10 +12,14 @@ Import subscribers in bulk using JSON or CSV formats.For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).:::+:::note+Bulk import endpoints are workspace-scoped. Requests require a JWT bearer token and the `X-Posta-Workspace-Id` header.+:::+## JSON Import```-POST /api/v1/users/me/subscribers/import/json+POST /api/v1/workspaces/current/subscribers/import/json``````json@@ -57,7 +61,7 @@ Duplicate emails (already existing) are skipped, not updated.## CSV Import```-POST /api/v1/users/me/subscribers/import/csv+POST /api/v1/workspaces/current/subscribers/import/csvContent-Type: multipart/form-data```@@ -81,9 +85,7 @@ Map CSV columns to subscriber fields using a JSON object where keys are column i"0": "email","1": "name","2": "custom_fields.company",- "3": "custom_fields.role",- "4": "timezone",- "5": "language"+ "3": "custom_fields.role"}```@@ -92,8 +94,9 @@ Custom fields use dot notation: `custom_fields.field_name`.### Example```bash-curl -X POST http://localhost:9000/api/v1/users/me/subscribers/import/csv \- -H "Authorization: Bearer <your-token>" \+curl -X POST http://localhost:9000/api/v1/workspaces/current/subscribers/import/csv \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \-F "[email protected]" \-F 'column_mapping={"0":"email","1":"name","2":"custom_fields.company"}'```diff --git a/docs/docs/subscribers/subscriber-lists.md b/docs/docs/subscribers/subscriber-lists.mdindex b7315bd..b56ec81 100644--- a/docs/docs/subscribers/subscriber-lists.md+++ b/docs/docs/subscribers/subscriber-lists.md@@ -12,10 +12,14 @@ Subscriber lists group subscribers for use in campaigns. Lists can be **static**For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).:::+:::note+List management endpoints are workspace-scoped and require a JWT bearer token and the `X-Posta-Workspace-Id` header. The public subscribe/unsubscribe/resubscribe endpoints use an API key instead — see [Public Subscribe Operations](#public-subscribe-operations-api-key).+:::+## Creating a List```-POST /api/v1/users/me/subscriber-lists+POST /api/v1/workspaces/current/subscriber-lists```### Static List@@ -55,7 +59,7 @@ Dynamic lists automatically include all subscribers matching the filter rules. M## Listing Lists```-GET /api/v1/users/me/subscriber-lists?page=0&size=20+GET /api/v1/workspaces/current/subscriber-lists?page=0&size=20```Response includes `member_count` for each list.@@ -63,13 +67,13 @@ Response includes `member_count` for each list.## Getting a List```-GET /api/v1/users/me/subscriber-lists/{id}+GET /api/v1/workspaces/current/subscriber-lists/{id}```## Updating a List```-PUT /api/v1/users/me/subscriber-lists/{id}+PUT /api/v1/workspaces/current/subscriber-lists/{id}```All fields are optional.@@ -77,7 +81,7 @@ All fields are optional.## Deleting a List```-DELETE /api/v1/users/me/subscriber-lists/{id}+DELETE /api/v1/workspaces/current/subscriber-lists/{id}```## Managing Members (Static Lists)@@ -85,7 +89,7 @@ DELETE /api/v1/users/me/subscriber-lists/{id}### Add a Subscriber```-POST /api/v1/users/me/subscriber-lists/{id}/members+POST /api/v1/workspaces/current/subscriber-lists/{id}/members``````json@@ -99,7 +103,7 @@ Only works for static lists. Adding a subscriber to a dynamic list returns an er### Remove a Subscriber```-DELETE /api/v1/users/me/subscriber-lists/{id}/members+DELETE /api/v1/workspaces/current/subscriber-lists/{id}/members``````json@@ -111,7 +115,7 @@ DELETE /api/v1/users/me/subscriber-lists/{id}/members### List Members```-GET /api/v1/users/me/subscriber-lists/{id}/members?page=0&size=20+GET /api/v1/workspaces/current/subscriber-lists/{id}/members?page=0&size=20```## Preview Segment@@ -119,7 +123,7 @@ GET /api/v1/users/me/subscriber-lists/{id}/members?page=0&size=20Test filter rules before creating a dynamic list:```-POST /api/v1/users/me/subscriber-lists/preview-segment+POST /api/v1/workspaces/current/subscriber-lists/preview-segment``````json@@ -161,3 +165,73 @@ Each rule has three properties:| `value` | Value to compare against |Filter rules are combined with AND logic — subscribers must match all rules to be included.++## Public Subscribe Operations (API Key)++These endpoints are authenticated with an API key (`Authorization: Bearer <api_key>`) and do **not** require the `X-Posta-Workspace-Id` header. They are intended for external integrations such as sign-up forms and automation tools.++### Subscribe++Adds an email to a named list, creating the list on first use. Any prior per-list opt-out for the same (list, email) is cleared.++```+POST /api/v1/subscriber-lists/subscribe+```++```json+{+ "email": "[email protected]",+ "name": "Jane Doe",+ "list": "Newsletter"+}+```++`email` and `list` are required. `name` is optional and is only applied when the subscriber is new.++Response:++```json+{+ "success": true,+ "data": {+ "list_id": 3,+ "subscriber_id": 42,+ "email": "[email protected]",+ "action": "subscribed",+ "list_created": false,+ "subscriber_created": true,+ "member_added": true+ }+}+```++### Unsubscribe++Opts an email out of a specific list without changing the subscriber's global status.++```+POST /api/v1/subscriber-lists/{id}/unsubscribe+```++```json+{+ "email": "[email protected]",+ "reason": "user_request"+}+```++`email` is required. `reason` is optional (defaults to `"api"`).++### Resubscribe++Reverses a list-scoped opt-out and re-adds the subscriber to the list (static lists only). Idempotent.++```+POST /api/v1/subscriber-lists/{id}/resubscribe+```++```json+{+ "email": "[email protected]"+}+```diff --git a/docs/docs/subscribers/subscriber-management.md b/docs/docs/subscribers/subscriber-management.mdindex 02c70f0..cf8038b 100644--- a/docs/docs/subscribers/subscriber-management.md+++ b/docs/docs/subscribers/subscriber-management.md@@ -12,10 +12,14 @@ Subscribers represent people who receive campaign emails. Each subscriber has anFor the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).:::+:::note+All subscriber management endpoints are workspace-scoped. Requests require a JWT bearer token and the `X-Posta-Workspace-Id` header.+:::+## Creating a Subscriber```-POST /api/v1/users/me/subscribers+POST /api/v1/workspaces/current/subscribers``````json@@ -46,7 +50,7 @@ Only `email` is required. Status defaults to `subscribed`.## Listing Subscribers```-GET /api/v1/users/me/subscribers?page=0&size=20+GET /api/v1/workspaces/current/subscribers?page=0&size=20```Optional query parameters:@@ -61,13 +65,13 @@ Optional query parameters:## Getting a Subscriber```-GET /api/v1/users/me/subscribers/{id}+GET /api/v1/workspaces/current/subscribers/{id}```## Updating a Subscriber```-PUT /api/v1/users/me/subscribers/{id}+PUT /api/v1/workspaces/current/subscribers/{id}``````json@@ -85,7 +89,7 @@ All fields are optional. When status changes to `unsubscribed`, the `unsubscribe## Deleting a Subscriber```-DELETE /api/v1/users/me/subscribers/{id}+DELETE /api/v1/workspaces/current/subscribers/{id}```## Custom Fieldsdiff --git a/docs/docs/templates/creating-templates.md b/docs/docs/templates/creating-templates.mdindex 01e5e82..dc5d7a9 100644--- a/docs/docs/templates/creating-templates.md+++ b/docs/docs/templates/creating-templates.md@@ -9,14 +9,15 @@ description: Create and manage email templates## Create a Template```-POST /api/v1/users/me/templates+POST /api/v1/workspaces/current/templates```-**Authentication:** JWT token+**Authentication:** JWT token + `X-Posta-Workspace-Id` header```bash-curl -X POST http://localhost:9000/api/v1/users/me/templates \+curl -X POST http://localhost:9000/api/v1/workspaces/current/templates \-H "Authorization: Bearer <jwt-token>" \+ -H "X-Posta-Workspace-Id: 1" \-H "Content-Type: application/json" \-d '{"name": "welcome",@@ -51,13 +52,13 @@ Template names must be unique. A `409 Conflict` is returned if the name already## List Templates```-GET /api/v1/users/me/templates?page=1&size=20+GET /api/v1/workspaces/current/templates?page=1&size=20```## Update a Template```-PUT /api/v1/users/me/templates/{id}+PUT /api/v1/workspaces/current/templates/{id}``````json@@ -71,7 +72,7 @@ PUT /api/v1/users/me/templates/{id}## Delete a Template```-DELETE /api/v1/users/me/templates/{id}+DELETE /api/v1/workspaces/current/templates/{id}```Returns `204 No Content`.diff --git a/docs/docs/templates/import-export.md b/docs/docs/templates/import-export.mdindex c0ade38..e5748cd 100644--- a/docs/docs/templates/import-export.md+++ b/docs/docs/templates/import-export.md@@ -11,7 +11,7 @@ Export templates as JSON and import them into other Posta instances. This is use## Export a Template```-GET /api/v1/users/me/templates/{templateId}/export+GET /api/v1/workspaces/current/templates/{templateId}/export```Returns the complete template including all versions and localizations as a JSON file.@@ -42,14 +42,15 @@ Returns the complete template including all versions and localizations as a JSON## Import a Template```-POST /api/v1/users/me/templates/import+POST /api/v1/workspaces/current/templates/import```Send the exported JSON as the request body. Returns `201 Created` with the new template.```bash-curl -X POST http://localhost:9000/api/v1/users/me/templates/import \+curl -X POST http://localhost:9000/api/v1/workspaces/current/templates/import \-H "Authorization: Bearer <jwt-token>" \+ -H "X-Posta-Workspace-Id: 1" \-H "Content-Type: application/json" \-d @template-export.json```diff --git a/docs/docs/templates/languages.md b/docs/docs/templates/languages.mdnew file mode 100644index 0000000..b442ab8--- /dev/null+++ b/docs/docs/templates/languages.md@@ -0,0 +1,116 @@+---+sidebar_position: 5+title: Languages+description: Manage the languages used for template localizations+---++# Languages++Languages are a workspace-level resource that defines which locales your+templates can be localized into. Each [template localization](/docs/templates/localization)+references a language by its `code`, so you typically create the languages you+need before adding localized content.++## What a language record is++A language record has these fields:++| Field | Type | Description |+|---|---|---|+| `id` | integer | Auto-generated identifier. |+| `code` | string | The locale code used to reference the language, e.g. `en`, `fr`, `de` (max 10 chars). |+| `name` | string | Human-readable name, e.g. `English`, `French`. |+| `is_default` | boolean | Whether this is the workspace's default language. Only one language can be the default — setting a new default clears the previous one. |+| `created_at` | timestamp | When the language was created. |++All language routes are workspace-scoped: they require a JWT plus the+`X-Posta-Workspace-Id` header (or a workspace-scoped API key, in which case the+header is implied).++## Create a Language++```+POST /api/v1/workspaces/current/languages+```++```json+{+ "code": "fr",+ "name": "French",+ "is_default": false+}+```++`code` and `name` are required. Set `is_default` to `true` to make this the+workspace default; any existing default is cleared automatically.++```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/languages \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{+ "code": "fr",+ "name": "French",+ "is_default": false+ }'+```++Response (`201`):++```json+{+ "success": true,+ "data": {+ "id": 1,+ "code": "fr",+ "name": "French",+ "is_default": false,+ "created_at": "2026-01-01T00:00:00Z"+ }+}+```++:::info+A `409 Conflict` is returned if the language code already exists in the workspace.+:::++## List Languages++```+GET /api/v1/workspaces/current/languages?page=1&size=20+```++Returns a paginated list of the workspace's languages.++## Update a Language++```+PUT /api/v1/workspaces/current/languages/{id}+```++```json+{+ "name": "Français",+ "is_default": true+}+```++All fields are optional. Provide only the fields you want to change. Setting+`is_default` to `true` clears the previous default language.++## Delete a Language++```+DELETE /api/v1/workspaces/current/languages/{id}+```++Returns `204 No Content`.++## Relationship to localizations++A language defines a locale at the workspace level. Template content is then+localized per template version: each localization stores `subject_template`,+`html_template`, and `text_template` for a given `language` code. See+[Localization](/docs/templates/localization) for adding and managing localized+template content, and how a language is resolved at send time.diff --git a/docs/docs/templates/localization.md b/docs/docs/templates/localization.mdindex 6e4f78d..75e5c3b 100644--- a/docs/docs/templates/localization.md+++ b/docs/docs/templates/localization.md@@ -10,53 +10,42 @@ Add localized versions of templates for different languages. Localizations are a## Managing Languages-Before adding localizations, create the languages you need:--### Create a Language--```-POST /api/v1/users/me/languages-```--```json-{- "code": "fr",- "name": "French"-}-```--### List Languages--```-GET /api/v1/users/me/languages-```+Before adding localizations, create the languages you need. Languages are a+workspace-level resource — see [Languages](/docs/templates/languages) for the+full CRUD reference. Each localization references a language by its `code`+(for example `fr`).## Adding Localizations### Add a Localization to a Version```-POST /api/v1/users/me/templates/{templateId}/versions/{versionId}/localizations+POST /api/v1/workspaces/current/templates/{templateId}/versions/{versionId}/localizations``````json{- "language_id": "language-uuid",- "html": "<h1>Bienvenue, {{name}} !</h1><p>Merci de nous avoir rejoints.</p>",- "text": "Bienvenue, {{name}} ! Merci de nous avoir rejoints."+ "language": "fr",+ "subject_template": "Bienvenue, {{name}} !",+ "html_template": "<h1>Bienvenue, {{name}} !</h1><p>Merci de nous avoir rejoints.</p>",+ "text_template": "Bienvenue, {{name}} ! Merci de nous avoir rejoints."}```+`language` and `subject_template` are required. `html_template` and+`text_template` are optional, as is `builder_json` (the visual builder layout).+Response (`201`):```json{"success": true,"data": {- "id": "localization-uuid",- "language_id": "language-uuid",- "html": "...",- "text": "..."+ "id": 1,+ "language": "fr",+ "subject_template": "Bienvenue, {{name}} !",+ "html_template": "...",+ "text_template": "..."}}```@@ -68,26 +57,27 @@ A `409 Conflict` is returned if the language already exists for this version.### List Localizations```-GET /api/v1/users/me/templates/{templateId}/versions/{versionId}/localizations+GET /api/v1/workspaces/current/templates/{templateId}/versions/{versionId}/localizations```### Update a Localization```-PUT /api/v1/users/me/localizations/{localizationId}+PUT /api/v1/workspaces/current/localizations/{localizationId}``````json{- "html": "<h1>Updated French content</h1>",- "text": "Updated French content"+ "subject_template": "Bienvenue !",+ "html_template": "<h1>Updated French content</h1>",+ "text_template": "Updated French content"}```### Delete a Localization```-DELETE /api/v1/users/me/localizations/{localizationId}+DELETE /api/v1/workspaces/current/localizations/{localizationId}```## Sending with Language@@ -128,12 +118,12 @@ curl -X POST http://localhost:9000/api/v1/emails/send-template \## Preview a Localized Version```-POST /api/v1/users/me/templates/{templateId}/versions/{versionId}/preview+POST /api/v1/workspaces/current/templates/{templateId}/versions/{versionId}/preview``````json{- "language_id": "language-uuid",+ "language": "fr","template_data": {"name": "Marie"}}```diff --git a/docs/docs/templates/preview-and-test.md b/docs/docs/templates/preview-and-test.mdindex d0558e6..7de262f 100644--- a/docs/docs/templates/preview-and-test.md+++ b/docs/docs/templates/preview-and-test.md@@ -13,7 +13,7 @@ Preview rendered templates and send test emails before going live.Render a template with sample data without sending:```-POST /api/v1/users/me/templates/preview+POST /api/v1/workspaces/current/templates/preview``````json@@ -45,7 +45,7 @@ Response:Send a test email using a specific template:```-POST /api/v1/users/me/templates/{templateId}/send-test+POST /api/v1/workspaces/current/templates/{templateId}/send-test``````jsondiff --git a/docs/docs/templates/stylesheets.md b/docs/docs/templates/stylesheets.mdindex abc52fd..b7bdfbe 100644--- a/docs/docs/templates/stylesheets.md+++ b/docs/docs/templates/stylesheets.md@@ -15,7 +15,7 @@ Most email clients strip `<style>` tags and external stylesheets. Posta automati## Create a Stylesheet```-POST /api/v1/users/me/stylesheets+POST /api/v1/workspaces/current/stylesheets``````json@@ -28,13 +28,13 @@ POST /api/v1/users/me/stylesheets## List Stylesheets```-GET /api/v1/users/me/stylesheets?page=1&size=20+GET /api/v1/workspaces/current/stylesheets?page=1&size=20```## Update a Stylesheet```-PUT /api/v1/users/me/stylesheets/{id}+PUT /api/v1/workspaces/current/stylesheets/{id}``````json@@ -47,7 +47,7 @@ PUT /api/v1/users/me/stylesheets/{id}## Delete a Stylesheet```-DELETE /api/v1/users/me/stylesheets/{id}+DELETE /api/v1/workspaces/current/stylesheets/{id}```Returns `204 No Content`.diff --git a/docs/docs/templates/versioning.md b/docs/docs/templates/versioning.mdindex 38724f5..23d17ea 100644--- a/docs/docs/templates/versioning.md+++ b/docs/docs/templates/versioning.md@@ -11,13 +11,13 @@ Each template can have multiple versions. Only one version is active at a time## List Versions```-GET /api/v1/users/me/templates/{templateId}/versions+GET /api/v1/workspaces/current/templates/{templateId}/versions```## Create a New Version```-POST /api/v1/users/me/templates/{templateId}/versions+POST /api/v1/workspaces/current/templates/{templateId}/versions``````json@@ -45,7 +45,7 @@ Response (`201`):## Update a Version```-PUT /api/v1/users/me/templates/{templateId}/versions/{versionId}+PUT /api/v1/workspaces/current/templates/{templateId}/versions/{versionId}``````json@@ -61,7 +61,7 @@ PUT /api/v1/users/me/templates/{templateId}/versions/{versionId}Switch the active version used for sending:```-POST /api/v1/users/me/templates/{templateId}/activate/{versionId}+POST /api/v1/workspaces/current/templates/{templateId}/activate/{versionId}```The response includes the updated template with the new `active_version_id`.@@ -69,7 +69,7 @@ The response includes the updated template with the new `active_version_id`.## Delete a Version```-DELETE /api/v1/users/me/templates/{templateId}/versions/{versionId}+DELETE /api/v1/workspaces/current/templates/{templateId}/versions/{versionId}```Returns `204 No Content`.diff --git a/docs/docs/tracking/overview.md b/docs/docs/tracking/overview.mdnew file mode 100644index 0000000..7e16310--- /dev/null+++ b/docs/docs/tracking/overview.md@@ -0,0 +1,131 @@+---+sidebar_position: 1+title: Tracking Overview+description: How Posta tracks email opens and clicks, the hosted web view, and where engagement data lands+---++# Tracking & Engagement++Posta measures engagement by injecting a 1×1 open-tracking pixel and rewriting links+for click tracking when a campaign is sent. It also serves a hosted "view in+browser" page. All of these are served from public, unauthenticated endpoints under+`/api/v1/t/*` so that recipients and mailbox providers can reach them.++:::info Public endpoints+Everything under `/api/v1/t/*` is **public — no authentication**. These URLs are meant+to be opened by email recipients and fetched by mailbox providers. They carry their+own HMAC-signed tokens/signatures instead of an `Authorization` header, so a missing+or tampered signature returns `404`.+:::++## Open tracking++```+GET /api/v1/t/o/{message_id}.gif+```++When a campaign message is built, Posta injects a hidden tracking pixel just before+`</body>`:++```html+<img src="http://localhost:9000/api/v1/t/o/123.gif?sig=..." width="1" height="1" alt="" style="display:none" />+```++Opening the email loads the GIF, and Posta records an **open** event. Details:++- The `sig` query parameter is a mandatory HMAC signature over the message ID.+ A request with no signature or a bad signature returns `404` and records nothing,+ so a third party hitting the predictable `/t/o/{message_id}.gif` path cannot+ inflate your metrics.+- The endpoint always returns a 1×1 transparent GIF with `Cache-Control: no-cache`.+- Requests from known bot user-agents (such as security scanners and link+ pre-fetchers) are served the pixel but **not** counted.+- The first open stamps `opened_at` on the campaign message; every open is also+ stored as an event for total/repeat-open metrics.++## Click tracking++```+GET /api/v1/t/c/{message_id}/{hash}+```++Every `http(s)` link in the HTML body is rewritten to a Posta redirect URL before+the message is sent. A rewritten link looks like:++```+http://localhost:9000/api/v1/t/c/123/ab12cd34ef56gh78?sig=...+```++When the recipient clicks it, Posta records a **click** event and then issues a+`302` redirect to the original destination. Details:++- `{hash}` is a deterministic hash of the campaign + original URL; Posta stores the+ original URL and looks it up on each click.+- The `sig` query parameter is a mandatory HMAC signature; a missing or bad+ signature returns `404`.+- Only `http://` and `https://` destinations are rewritten and redirected. `mailto:`+ and `tel:` links, and any link that already points at Posta's own `/t/` tracking+ paths, are left untouched. Non-http redirect targets are rejected with `400` to+ prevent open-redirect/SSRF abuse.+- Bot user-agents are redirected but not counted.+- The first click stamps `clicked_at` on the message; per-link click counts are+ incremented, and a unique click event is recorded per link per message.++## Enabling and disabling tracking++Tracking is a **server-side capability**, not a per-send or per-workspace toggle:++- For **campaign** sends, open-pixel injection and link rewriting are applied+ automatically to every message whenever the tracking service is configured (it+ requires a public base URL and an HMAC signing key on the server). There is no+ per-campaign or workspace checkbox to turn it off — if tracking is configured, a+ campaign send is tracked.+- For **transactional** sends (`POST /api/v1/emails/send` and friends), Posta does+ **not** rewrite links or inject an open pixel. Transactional messages only gain+ Posta-hosted links when the template references a `{{ posta_* }}` system variable+ (see [System Variables](../templates/system-variables.md)) or when the send names a+ Posta-managed unsubscribe list (see [Unsubscribe & One-Click](./unsubscribe.md)).++## Where the data goes++Open and click events feed **campaign analytics**. The authenticated, workspace-scoped+endpoint returns aggregate counts, per-variant breakdowns (for A/B tests), per-link+click totals, and open/click time series:++```+GET /api/v1/workspaces/current/campaigns/{id}/analytics+```++```bash+curl http://localhost:9000/api/v1/workspaces/current/campaigns/42/analytics \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```++The response includes `analytics`, optional `variant_analytics`, `links`,+`open_series`, and `click_series`. See [Campaigns](../campaigns/overview.md) for how+these surface in the dashboard.++## View in browser (web view)++```+GET /api/v1/t/v/{token}+```++Posta hosts a "view this email in a browser" page for any sent message. The link is+produced by the `{{ posta_web_view_url }}` system variable (and its+`{{ posta_mail_web_link }}` alias). The `{token}` is an HMAC-signed, **expiring**+capability bound to the email's opaque UUID — it defaults to a 90-day lifetime, and an+invalid or expired token renders a "link is invalid or has expired" page.++The hosted page:++- Renders the exact HTML that was sent (falling back to the text body when there is+ no HTML).+- **Strips the open-tracking pixel**, so loading the web view does not inflate open+ metrics.+- Is served with a restrictive `Content-Security-Policy`, `X-Robots-Tag: noindex,+ nofollow`, `Referrer-Policy: no-referrer`, and no cookies.++See [System Variables](../templates/system-variables.md) for how to add the web-view+link to a template.diff --git a/docs/docs/tracking/unsubscribe.md b/docs/docs/tracking/unsubscribe.mdnew file mode 100644index 0000000..2adf929--- /dev/null+++ b/docs/docs/tracking/unsubscribe.md@@ -0,0 +1,142 @@+---+sidebar_position: 2+title: Unsubscribe & One-Click+description: Hosted unsubscribe pages, RFC 8058 one-click unsubscribe, and List-Unsubscribe headers+---++# Unsubscribe & One-Click++Posta hosts the unsubscribe flow so recipients (and their mailbox providers) can opt+out without an account. All of these endpoints live under `/api/v1/t/*` and are+**public — no authentication**. They carry an HMAC-signed token instead of an+`Authorization` header.++:::info Public endpoints+These URLs are opened by recipients and POSTed to by mailbox providers (Gmail,+Apple Mail, Outlook, …) acting on the recipient's behalf. There is no API key or JWT+involved. A missing, malformed, or expired token returns a `404` page.+:::++## Campaign unsubscribe (hosted page + confirm)++```+GET /api/v1/t/u/{token}+POST /api/v1/t/u/{token}+```++This is the link behind `{{ posta_unsubscribe_url }}` for **campaign** sends.++- `GET` renders a small confirmation page showing the recipient's email and a+ "Confirm Unsubscribe" button.+- `POST` (the form submit) performs the opt-out: it suppresses the subscriber on+ that campaign's list, marks the campaign message as unsubscribed, and records an+ unsubscribe event for analytics. Only that list is affected — other lists the+ recipient belongs to are untouched.++The `{token}` is an HMAC-signed token encoding the campaign message ID.++## Transactional one-click unsubscribe (RFC 8058)++```+GET /api/v1/t/u/tx/{token}+POST /api/v1/t/u/tx/{token}+```++This is the link behind `{{ posta_unsubscribe_url }}` for **transactional** sends and+the target of the RFC 8058 `List-Unsubscribe-Post` header.++- `GET` renders a confirmation page.+- `POST` is the RFC 8058 **one-click** endpoint: it opts the recipient out with no+ further interaction and no session. It is idempotent and safe for a mailbox+ provider to call automatically.++On a `POST`, every recipient on the email is added to the workspace's suppression+list. If the send referenced a Posta-managed unsubscribe list, the suppression is+**scoped to that list** (`list_unsubscribe` kind); otherwise it is a hard global+suppression. Each opt-out also fires an `email.unsubscribed` webhook carrying the+email UUID, the recipient address, and the list ID.++The `{token}` is an HMAC-signed token with a `tx:` prefix that binds it to the+transactional email ID, so it cannot be replayed against the campaign unsubscribe+handler.++## List-Unsubscribe headers on outgoing mail++Posta sets the standard `List-Unsubscribe` (RFC 2369) and `List-Unsubscribe-Post`+(RFC 8058) headers so mailbox providers show a native "Unsubscribe" control.++For a transactional send, configure this with the `unsubscribe` object on+`POST /api/v1/emails/send`:++```json+{+ "from": "[email protected]",+ "to": ["[email protected]"],+ "subject": "Weekly digest",+ "html": "<p>...</p>",+ "unsubscribe": {+ "list_id": 7+ }+}+```++The `unsubscribe` object supports two mutually exclusive modes:++- **Posta-managed** — set `list_id` to reference an existing unsubscribe list. Posta+ mints the signed one-click URL (`/api/v1/t/u/tx/{token}`), emits both headers, and a+ click suppresses the recipient on that list only. One-click is implied on this path.+- **Caller-managed** — set `url` to your own endpoint (and optionally `mailto`).+ Posta only emits the header; you own the endpoint. Set `one_click: true` to also+ emit `List-Unsubscribe-Post` — this requires an `https` URL.++| Field | Type | Notes |+|---|---|---|+| `list_id` | integer | Reference a Posta `UnsubscribeList`. Mutually exclusive with `url`. |+| `url` | string | Caller-managed unsubscribe endpoint / RFC 8058 POST target. Mutually exclusive with `list_id`. |+| `mailto` | string | Optional `mailto:` URI emitted alongside `url` (RFC 2369). A bare address is accepted; Posta prepends `mailto:`. |+| `one_click` | boolean | Emit `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058). Applies to the `https` URL target only; implied on the `list_id` path. |++On the wire Posta emits the mailto first, then the https URL:++```+List-Unsubscribe: <mailto:[email protected]>, <http://localhost:9000/api/v1/t/u/tx/...>+List-Unsubscribe-Post: List-Unsubscribe=One-Click+```++For **campaign** sends, Posta automatically points the `List-Unsubscribe` header at+the campaign unsubscribe URL (`/api/v1/t/u/{token}`) and enables one-click — there is+nothing to configure per campaign.++:::note Deprecated fields+The top-level `list_unsubscribe_url` and `list_unsubscribe_post` fields are+deprecated. Use the `unsubscribe` object instead.+:::++## Relationship to the unsubscribe URL system variable++The `{{ posta_unsubscribe_url }}` system variable resolves to the right hosted+endpoint depending on the send type: the campaign unsubscribe page for campaigns, and+the RFC 8058 one-click endpoint for transactional sends. The link is only generated+once the message identity is known, so it renders as its own name in template+previews. See [System Variables](../templates/system-variables.md).++## Unsubscribe lists and suppression++Posta-managed unsubscribe lists are workspace-scoped resources you manage via the API:++```+POST /api/v1/workspaces/current/unsubscribe-lists+GET /api/v1/workspaces/current/unsubscribe-lists+GET /api/v1/workspaces/current/unsubscribe-lists/{id}+PUT /api/v1/workspaces/current/unsubscribe-lists/{id}+DELETE /api/v1/workspaces/current/unsubscribe-lists/{id}+```++A list has a `name`, an optional `public_name` and `description`, and an `active`+flag. Referencing one by `list_id` on a send lets Posta scope a one-click opt-out to+that list.++When a recipient unsubscribes, they land on your **suppression list** so future sends+skip them. See [Suppression List](../contacts/suppression-list.md) for managing+suppressions and [Contact Management](../contacts/contact-management.md) for how+suppression interacts with contacts.diff --git a/docs/docs/webhooks/audit-log.md b/docs/docs/webhooks/audit-log.mdindex 47b3f69..8bc4135 100644--- a/docs/docs/webhooks/audit-log.md+++ b/docs/docs/webhooks/audit-log.md@@ -1,26 +1,33 @@---sidebar_position: 4title: Audit Log-description: Track user and system events+description: Track workspace operational and personal security events---# Audit Log-Posta maintains an audit trail of user and system events.+Posta maintains two separate audit trails depending on what you need to audit.-## View Audit Log+## Workspace Operational Audit Log+The workspace audit log records operational activity scoped to a workspace: API key creation/revocation, template changes, SMTP server changes, webhook changes, and similar configuration actions. Requires the `admin` or `owner` workspace role.++```+GET /api/v1/workspaces/current/audit-log?page=1&size=20```-GET /api/v1/users/me/audit-log?page=1&size=20&category=email++```bash+curl "http://localhost:9000/api/v1/workspaces/current/audit-log?page=1&size=20" \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"```### Query Parameters| Parameter | Description ||-----------|-------------|-| `page` | Page number |-| `size` | Items per page |-| `category` | Filter by category: `user`, `email`, `system`, `audit` |+| `page` | Page number (default: 0) |+| `size` | Items per page (default: 20) |Response:@@ -29,29 +36,69 @@ Response:"success": true,"data": [{- "type": "email.sent",+ "id": 42,+ "category": "audit",+ "type": "apikey.created",+ "workspace_id": 1,+ "actor_id": 1,"actor_name": "[email protected]",- "message": "Email sent to [email protected]",- "timestamp": "2026-01-01T00:00:01Z"+ "client_ip": "203.0.113.42",+ "message": "API key created: My Key",+ "created_at": "2026-01-01T00:00:01Z"},{+ "id": 41,+ "category": "audit",+ "type": "webhook.created",+ "workspace_id": 1,+ "actor_id": 1,+ "actor_name": "[email protected]",+ "client_ip": "203.0.113.42",+ "message": "Webhook created: https://your-app.com/webhooks/posta",+ "created_at": "2026-01-01T00:00:00Z"+ }+ ]+}+```++## Personal Security Audit Log++The personal audit log records security-sensitive events for the authenticated user's account: logins, password changes, 2FA changes, and session activity. This log is not workspace-scoped.++```+GET /api/v1/users/me/audit-log?page=1&size=20+```++```bash+curl "http://localhost:9000/api/v1/users/me/audit-log?page=1&size=20" \+ -H "Authorization: Bearer <jwt>"+```++Example entries:++```json+{+ "success": true,+ "data": [+ {+ "id": 10,+ "category": "audit","type": "user.login","actor_name": "[email protected]",- "message": "User logged in from 203.0.113.42",- "timestamp": "2026-01-01T00:00:00Z"+ "client_ip": "203.0.113.42",+ "message": "User logged in",+ "created_at": "2026-01-01T00:00:00Z"}]}```-## Event Categories+## Summary-| Category | Events |-|----------|--------|-| `user` | Login, logout, profile updates, password changes, 2FA changes |-| `email` | Email sent, failed, retried, bounced |-| `system` | Server started, configuration changes |-| `audit` | API key created/revoked, template changes, SMTP changes |+| Log | Endpoint | Scope | Typical entries |+|-----|----------|-------|-----------------|+| Workspace operational | `GET /api/v1/workspaces/current/audit-log` | Workspace (admin/owner) | API keys, webhooks, SMTP, templates |+| Personal security | `GET /api/v1/users/me/audit-log` | Authenticated user | Login, password, 2FA, sessions |## Admin: Platform-Wide Eventsdiff --git a/docs/docs/webhooks/delivery-tracking.md b/docs/docs/webhooks/delivery-tracking.mdindex 86008f4..f8613f9 100644--- a/docs/docs/webhooks/delivery-tracking.md+++ b/docs/docs/webhooks/delivery-tracking.md@@ -10,8 +10,16 @@ Monitor the delivery status of your webhook notifications.## View Delivery History+Webhook deliveries are workspace-scoped:++```+GET /api/v1/workspaces/current/webhook-deliveries?page=1&size=20```-GET /api/v1/users/me/webhook-deliveries?page=1&size=20++```bash+curl http://localhost:9000/api/v1/workspaces/current/webhook-deliveries \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"```Response:@@ -21,18 +29,28 @@ Response:"success": true,"data": [{- "url": "https://your-app.com/webhooks/posta",- "status": 200,- "retry_count": 0,- "response": "{\"received\": true}",- "timestamp": "2026-01-01T00:00:01Z"+ "id": 1,+ "webhook_id": 3,+ "user_id": 1,+ "workspace_id": 1,+ "event": "email.sent",+ "status": "success",+ "http_status_code": 200,+ "error_message": "",+ "attempt": 1,+ "created_at": "2026-01-01T00:00:01Z"},{- "url": "https://your-app.com/webhooks/posta",- "status": 500,- "retry_count": 2,- "response": "Internal Server Error",- "timestamp": "2026-01-01T00:01:00Z"+ "id": 2,+ "webhook_id": 3,+ "user_id": 1,+ "workspace_id": 1,+ "event": "email.failed",+ "status": "failed",+ "http_status_code": 500,+ "error_message": "HTTP 500",+ "attempt": 3,+ "created_at": "2026-01-01T00:01:00Z"}]}@@ -42,11 +60,13 @@ Response:| Field | Description ||-------|-------------|-| `url` | Webhook endpoint URL |-| `status` | HTTP status code of the response |-| `retry_count` | Number of delivery attempts |-| `response` | Response body from your server |-| `timestamp` | When the delivery was attempted |+| `webhook_id` | ID of the webhook that fired |+| `event` | Event type that triggered the delivery |+| `status` | Outcome: `success` or `failed` |+| `http_status_code` | HTTP status code returned by your endpoint |+| `error_message` | Error detail when delivery failed |+| `attempt` | Which retry attempt this record represents |+| `created_at` | When the delivery was attempted |## Retry Policydiff --git a/docs/docs/webhooks/event-types.md b/docs/docs/webhooks/event-types.mdindex 10ae3ee..66a0607 100644--- a/docs/docs/webhooks/event-types.md+++ b/docs/docs/webhooks/event-types.md@@ -8,13 +8,13 @@ description: Available webhook event types## Email Events-Subscribe to these events when creating webhooks:-| Event | Description ||-------|-------------|| `email.sent` | Email was successfully delivered to the SMTP server || `email.failed` | Email delivery failed after all retries |-| `email.inbound` | An inbound message was received and forwarded |+| `email.unsubscribed` | Recipient unsubscribed via a one-click link |+| `email.complained` | Recipient filed a spam complaint |+| `email.inbound` | An inbound email was received (see [Inbound Email](#inbound-email)) |## Campaign Events@@ -23,55 +23,58 @@ Subscribe to these events when creating webhooks:| `campaign.started` | A campaign began sending || `campaign.completed` | A campaign finished sending all messages |-## Event Payload Structure+## Payload Shapes++### `email.sent`-All events share a common structure:+Fired when an email is successfully delivered to the SMTP server:```json{"event": "email.sent",- "timestamp": "2026-01-01T00:00:01Z",- "data": {- "email_id": "uuid",- "to": "[email protected]",- "from": "[email protected]",- "subject": "Hello",- "status": "sent",- "error_message": null- }+ "email_id": "550e8400-e29b-41d4-a716-446655440000",+ "timestamp": "2026-01-01T00:00:01Z"}```-### `email.sent`+### `email.failed`-Fired when an email is successfully delivered:+Fired when delivery fails after all retries:```json{- "event": "email.sent",- "data": {- "email_id": "uuid",- "to": "[email protected]",- "status": "sent",- "sent_at": "2026-01-01T00:00:01Z"- }+ "event": "email.failed",+ "email_id": "550e8400-e29b-41d4-a716-446655440000",+ "timestamp": "2026-01-01T00:00:01Z"}```-### `email.failed`+### `email.unsubscribed`-Fired when delivery fails after all retries:+Fired when a recipient opts out via a one-click unsubscribe link:```json{- "event": "email.failed",- "data": {- "email_id": "uuid",- "to": "[email protected]",- "status": "failed",- "error_message": "Connection refused",- "retry_count": 3- }+ "event": "email.unsubscribed",+ "email_uuid": "550e8400-e29b-41d4-a716-446655440000",+ "email": "[email protected]",+ "list_id": 7,+ "timestamp": "2026-01-01T00:00:01Z"+}+```++`list_id` is omitted when the unsubscribe is not scoped to a specific subscriber list.++### `email.complained`++Fired when a spam complaint is recorded (e.g. via the bounce webhook):++```json+{+ "event": "email.complained",+ "email_uuid": "550e8400-e29b-41d4-a716-446655440000",+ "email": "[email protected]",+ "timestamp": "2026-01-01T00:00:01Z"}```@@ -100,3 +103,35 @@ Fired when a campaign finishes sending all of its messages:"timestamp": "2026-01-01T00:00:01Z"}```++## Inbound Email++The `email.inbound` event fires when Posta receives an incoming message on a verified domain. Its payload is richer than the outbound events:++```json+{+ "event": "email.inbound",+ "timestamp": "2026-01-01T00:00:01Z",+ "inbound_id": "7d3f9a12-...",+ "from": "[email protected]",+ "to": ["[email protected]"],+ "subject": "Hello",+ "text_body": "Plain text body",+ "html_body": "<p>HTML body</p>",+ "headers": { "Reply-To": "[email protected]" },+ "attachments": [+ {+ "filename": "report.pdf",+ "content_type": "application/pdf",+ "size": 12345,+ "url": "https://..."+ }+ ],+ "size": 14200,+ "message_id": "<[email protected]>",+ "source": "smtp",+ "received_at": "2026-01-01T00:00:00Z"+}+```++For configuring inbound routing and managing received messages, see the Inbound Email section in the sidebar.diff --git a/docs/docs/webhooks/overview.md b/docs/docs/webhooks/overview.mdindex 80fb113..2e147de 100644--- a/docs/docs/webhooks/overview.md+++ b/docs/docs/webhooks/overview.md@@ -14,35 +14,70 @@ For the full request/response schema, see the interactive [API Reference](https:## Creating a Webhook-Create a webhook from the dashboard or via `POST /api/v1/users/me/webhooks`:+Webhooks are workspace-scoped. Create one via the dashboard or the API:-```json-{- "url": "https://your-app.com/webhooks/posta",- "events": ["email.sent", "email.failed", "campaign.completed"],- "secret": "your-webhook-secret"-}+```+POST /api/v1/workspaces/current/webhooks+```++```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/webhooks \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{+ "url": "https://your-app.com/webhooks/posta",+ "events": ["email.sent", "email.failed", "campaign.completed"]+ }'+```++Request body:++| Field | Type | Description |+|-------|------|-------------|+| `url` | string | HTTPS endpoint to receive events |+| `events` | array | One or more [event types](./event-types.md) to subscribe to |+| `filters` | array | Optional sender-address or domain filters |++:::note+The signing `secret` is generated automatically by Posta and returned in the creation response. Store it securely — it is used to verify the `X-Posta-Signature` header on every delivery.+:::++## Listing and Deleting Webhooks++```+GET /api/v1/workspaces/current/webhooks+DELETE /api/v1/workspaces/current/webhooks/{id}```## Webhook Payload-Posta sends a POST request with a JSON payload:+Posta sends a POST request with a JSON payload. For outbound email events the shape is:```json{"event": "email.sent",- "timestamp": "2026-01-01T00:00:01Z",- "data": {- "email_id": "550e8400-e29b-41d4-a716-446655440000",- "to": "[email protected]",- "status": "sent"- }+ "email_id": "550e8400-e29b-41d4-a716-446655440000",+ "timestamp": "2026-01-01T00:00:01Z"+}+```++For campaign events:++```json+{+ "event": "campaign.completed",+ "campaign_id": 42,+ "name": "Spring Newsletter",+ "timestamp": "2026-01-01T00:00:01Z"}```+See [Event Types](./event-types.md) for payload shapes of all events.+## Signature Verification-If a `secret` is configured, Posta includes an HMAC-SHA256 signature in the request header:+Posta generates a random signing secret per webhook and returns it in the creation response. Every delivery includes an HMAC-SHA256 signature header:```X-Posta-Signature: sha256=abc123...diff --git a/docs/docs/workspaces/members-and-invitations.md b/docs/docs/workspaces/members-and-invitations.mdnew file mode 100644index 0000000..0c83325--- /dev/null+++ b/docs/docs/workspaces/members-and-invitations.md@@ -0,0 +1,199 @@+---+sidebar_position: 2+title: Members and Invitations+description: Manage workspace members, roles, and invitations+---++# Members and Invitations++Workspaces are collaborative. Owners and admins add people by sending email invitations; once accepted, the invitee becomes a member with the role chosen at invitation time. All endpoints here use JWT bearer authentication. The `/workspaces/current/*` routes additionally require the `X-Posta-Workspace-Id` header.++## Members++### List members++```+GET /api/v1/workspaces/current/members+```++```bash+curl -X GET http://localhost:9000/api/v1/workspaces/current/members \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```++Response:++```json+{+ "data": [+ {+ "id": 5,+ "user_id": 42,+ "name": "Ada Lovelace",+ "email": "[email protected]",+ "role": "owner",+ "created_at": "2026-05-31T10:00:00Z"+ }+ ]+}+```++### Update a member's role++```+PUT /api/v1/workspaces/current/members/{member_id}+```++`member_id` is the **user ID** of the member (the `user_id` field returned by the list endpoint).++```json+{+ "role": "editor"+}+```++Valid roles are `admin`, `editor`, and `viewer`. The `owner` role cannot be assigned (`400`), and an existing owner's role cannot be changed (`400`). The member receives a role-change notification email. Returns a message payload on success.++### Remove a member++```+DELETE /api/v1/workspaces/current/members/{member_id}+```++Removes the member identified by their user ID and returns `204`. The workspace owner cannot be removed (`400`).++## Invitations (workspace side)++Owners and admins manage outgoing invitations under `/workspaces/current/invitations`.++### Invite a member++```+POST /api/v1/workspaces/current/invitations+```++```json+{+ "email": "[email protected]",+ "role": "editor"+}+```++Both fields are required. `role` may be `admin`, `editor`, or `viewer` — inviting as `owner` is rejected (`400`). If the email already belongs to a member, the request returns `409`. The inviter's email must be verified.++A pending invitation is created with a unique token, valid for **7 days**, and an invitation email is sent to the address with an accept link of the form `/<app>/invitations?token=<token>`.++Response (`201`):++```json+{+ "data": {+ "id": 12,+ "workspace_id": 1,+ "workspace": "",+ "email": "[email protected]",+ "role": "editor",+ "status": "pending",+ "expires_at": "2026-06-07T10:00:00Z",+ "created_at": "2026-05-31T10:00:00Z"+ }+}+```++```bash+curl -X POST http://localhost:9000/api/v1/workspaces/current/invitations \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{"email": "[email protected]", "role": "editor"}'+```++### List pending invitations++```+GET /api/v1/workspaces/current/invitations+```++Returns the workspace's pending invitations as an array of the object shown above.++### Cancel an invitation++```+DELETE /api/v1/workspaces/current/invitations/{id}+```++Deletes the pending invitation by its ID and returns `204`.++## Invitations (invitee side)++These routes are for the **recipient** of an invitation. They use JWT auth only and do **not** require the workspace header — the invitee is not yet a member.++### List my invitations++```+GET /api/v1/invitations+```++Lists all pending invitations addressed to the authenticated user's email. Each entry includes the originating workspace name in the `workspace` field:++```json+{+ "data": [+ {+ "id": 12,+ "workspace_id": 1,+ "workspace": "Acme Inc",+ "email": "[email protected]",+ "role": "editor",+ "status": "pending",+ "expires_at": "2026-06-07T10:00:00Z",+ "created_at": "2026-05-31T10:00:00Z"+ }+ ]+}+```++### Accept or decline by token++Used by the link in the invitation email.++```+POST /api/v1/invitations/accept+POST /api/v1/invitations/decline+```++```json+{+ "token": "<invitation_token>"+}+```++On accept, the invitee is added to the workspace with the invited role and the invitation is marked `accepted`. The invitation's email must match the authenticated user (`403` otherwise). Accepting a non-pending or expired invitation returns `400`; if the user is already a member the invitation is marked accepted and `409` is returned.++A successful accept returns the joined workspace:++```json+{+ "data": {+ "message": "joined workspace \"Acme Inc\"",+ "workspace_id": 1+ }+}+```++### Accept or decline by ID++Used by the dashboard when the user is viewing their pending invitations.++```+POST /api/v1/invitations/{id}/accept+POST /api/v1/invitations/{id}/decline+```++These take no body. The same validation applies: the invitation must be pending, not expired, and addressed to the authenticated user's email.++```bash+curl -X POST http://localhost:9000/api/v1/invitations/12/accept \+ -H "Authorization: Bearer <jwt>"+```diff --git a/docs/docs/workspaces/overview.md b/docs/docs/workspaces/overview.mdindex 8c5688d..01538e7 100644--- a/docs/docs/workspaces/overview.md+++ b/docs/docs/workspaces/overview.md@@ -1,100 +1,195 @@+---+sidebar_position: 1+title: Overview+description: Multi-tenant workspaces, roles, and the workspace context header+---+# Workspaces-Workspaces provide multi-tenant isolation within Posta. They work like GitHub Organizations — users have a **personal space** by default, and can optionally create **workspaces** to share resources with team members.+Workspaces provide multi-tenant isolation within Posta. They work like GitHub Organizations — every user has a **personal space** by default and can optionally create **workspaces** to share resources with team members.## Concepts-### Personal Space+### Personal space-Every user has a personal space where their resources (templates, SMTP servers, domains, contacts, API keys, etc.) live by default. No workspace is required — the platform works exactly as before for single users.+Every user has a personal space where their resources (templates, SMTP servers, domains, contacts, API keys, etc.) live by default. No workspace is required — the platform works for a single user out of the box. The personal space is itself a workspace flagged `is_personal: true`; it is owned by the user and cannot be deleted.### Workspaces-A workspace is an isolated environment where team members can collaborate. Resources created within a workspace are only visible to workspace members. Each workspace has:+A workspace is an isolated environment where team members collaborate. Resources created within a workspace are only visible to members of that workspace. Each workspace has:-- A unique **name** and **slug**+- A unique **name** and **slug** (a URL-friendly identifier)- An **owner** (the creator)-- **Members** with assigned roles-- Isolated resources (templates, SMTP servers, domains, API keys, contacts, emails, webhooks, etc.)+- **Members**, each with a role+- A **default language**+- Isolated operational resources (templates, SMTP servers, domains, API keys, contacts, subscribers, campaigns, emails, webhooks, etc.)### Roles-| Role | View | Create/Edit | Manage Members | Delete Workspace |-|------|------|-------------|----------------|------------------|-| **Owner** | Yes | Yes | Yes | Yes |-| **Admin** | Yes | Yes | Yes | No |-| **Editor** | Yes | Yes | No | No |-| **Viewer** | Yes | No | No | No |+Posta defines four workspace roles. Permissions are cumulative:-## Creating a Workspace+| Role | View resources | Create / edit resources | Manage members & invitations | Delete workspace |+|------|:---:|:---:|:---:|:---:|+| **owner** | Yes | Yes | Yes | Yes |+| **admin** | Yes | Yes | Yes | No |+| **editor** | Yes | Yes | No | No |+| **viewer** | Yes | No | No | No |-Navigate to **Workspaces** in the sidebar and click **Create Workspace**. Provide a name and slug (URL-friendly identifier).+There is exactly one owner per workspace: the creator. The owner role cannot be assigned through invitations or role updates, and the owner cannot be removed or have their role changed.-## Switching Context+:::note+Operational settings, the workspace audit log, and the GDPR data-management endpoints require the **admin** level or higher (owner or admin). Resource read/write follows the table above.+:::-Use the **workspace switcher** in the sidebar to switch between your personal space and any workspace you belong to. When you switch:+## API usage-- All resource views (templates, emails, contacts, etc.) show data from the selected context-- New resources you create are scoped to the selected context-- Analytics and dashboard stats reflect the selected context+Workspace management uses **JWT bearer authentication** (the dashboard/UI token), not API keys.-## Inviting Members+```+Authorization: Bearer <jwt>+```-Workspace owners and admins can invite users:+### Workspace context header-1. Go to **Workspaces** > select your workspace > **Manage**-2. Open the **Invitations** tab-3. Click **Invite** and enter the user's email and role+Routes under `/api/v1/workspaces/current/*` operate against the **active workspace**, which is resolved from the `X-Posta-Workspace-Id` header:++```+X-Posta-Workspace-Id: 1+```-Invited users will see pending invitations on the **Workspaces** page and can accept or decline directly from the dashboard.+```bash+curl -X GET http://localhost:9000/api/v1/workspaces/current/templates \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```-## Data Transfer+The header value is the numeric workspace ID. If you are not a member of that workspace the request is rejected with `403`. The header is **required** for every `/workspaces/current/*` route; omitting it returns `400 X-Posta-Workspace-Id header is required`.-Transfer your personal resources into a workspace:+:::caution+The correct header is `X-Posta-Workspace-Id`. Earlier drafts referred to `X-Workspace-ID` — that name is wrong and is not recognized by the API.+:::-1. Go to the workspace's **Manage** page-2. Open the **Data Transfer** tab-3. Select which resource types to transfer (templates, contacts, SMTP servers, etc.)-4. Click **Transfer**+To operate against your personal space, pass its workspace ID in the header (you can find it in the `GET /api/v1/workspaces` list, where `is_personal` is `true`).-Transferred resources will no longer appear in your personal space — they become workspace-scoped.+### Workspace-scoped API keys-## API Usage+API keys created inside a workspace context are bound to that workspace. When you authenticate with such a key, the active workspace is implied by the key itself, so the `X-Posta-Workspace-Id` header is **not** needed:-### Workspace Context Header+```bash+curl -X POST http://localhost:9000/api/v1/emails/send \+ -H "Authorization: Bearer <workspace_api_key>" \+ -H "Content-Type: application/json" \+ -d '{ ... }'+```-To interact with workspace-scoped resources via the API, include the `X-Workspace-ID` header:+This is how transactional sending and other API-key endpoints stay scoped to the right workspace without a header.++## Workspace management endpoints++All endpoints below use JWT auth. Those operating on `/current` additionally require the `X-Posta-Workspace-Id` header.++| Method | Path | Header required | Description |+|--------|------|:---:|-------------|+| `POST` | `/api/v1/workspaces` | No | Create a workspace (creator becomes owner) |+| `GET` | `/api/v1/workspaces` | No | List workspaces the user belongs to |+| `GET` | `/api/v1/workspaces/current` | Yes | Get the active workspace |+| `PUT` | `/api/v1/workspaces/current` | Yes | Update name / description / default language |+| `DELETE` | `/api/v1/workspaces/current` | Yes | Delete the workspace |+| `GET` | `/api/v1/workspaces/current/members` | Yes | List members |+| `PUT` | `/api/v1/workspaces/current/members/{member_id}` | Yes | Update a member's role |+| `DELETE` | `/api/v1/workspaces/current/members/{member_id}` | Yes | Remove a member |+| `POST` | `/api/v1/workspaces/current/invitations` | Yes | Invite a user by email |+| `GET` | `/api/v1/workspaces/current/invitations` | Yes | List pending invitations |+| `DELETE` | `/api/v1/workspaces/current/invitations/{id}` | Yes | Cancel a pending invitation |+| `GET` | `/api/v1/workspaces/invitations` | No | List the current user's pending invitations |+| `POST` | `/api/v1/workspaces/invitations/accept` | No | Accept an invitation by token |+| `POST` | `/api/v1/workspaces/invitations/decline` | No | Decline an invitation by token |+| `POST` | `/api/v1/workspaces/invitations/{id}/accept` | No | Accept an invitation by ID |+| `POST` | `/api/v1/workspaces/invitations/{id}/decline` | No | Decline an invitation by ID |+| `GET` | `/api/v1/workspaces/current/plan` | Yes | Get the effective plan and limits |+| `GET` | `/api/v1/workspaces/current/settings` | Yes | Get operational settings |+| `PUT` | `/api/v1/workspaces/current/settings` | Yes | Update operational settings (admin+) |+| `GET` | `/api/v1/workspaces/current/audit-log` | Yes | Workspace audit trail (admin+) |++Member and invitation details are documented in [Members and Invitations](./members-and-invitations). Operational settings, plan, and the audit log are documented in [Settings, Plan, and Audit Log](./settings).++## Creating a workspace++```+POST /api/v1/workspaces+```++Request body:++```json+{+ "name": "Acme Inc",+ "slug": "acme",+ "description": "Marketing and transactional mail",+ "default_language": "en"+}+```++Only `name` is required. If `slug` is omitted it is derived from the name; slugs must contain only lowercase letters, numbers, and hyphens, and must be unique. `default_language` defaults to `en`. The caller becomes the workspace **owner**.```bash-curl -X GET http://localhost:9000/api/v1/users/me/templates \- -H "Authorization: Bearer YOUR_TOKEN" \- -H "X-Workspace-ID: 1"-```--If the header is omitted, the request operates in the user's personal space.--### Workspace-Scoped API Keys--API keys created within a workspace context are automatically scoped to that workspace. Requests using a workspace-scoped API key will operate within the workspace without needing the `X-Workspace-ID` header.--### Workspace Management Endpoints--| Method | Path | Description |-|--------|------|-------------|-| `POST` | `/api/v1/workspaces` | Create workspace |-| `GET` | `/api/v1/workspaces` | List user's workspaces |-| `GET` | `/api/v1/workspaces/current` | Get current workspace |-| `PUT` | `/api/v1/workspaces/current` | Update workspace |-| `DELETE` | `/api/v1/workspaces/current` | Delete workspace |-| `GET` | `/api/v1/workspaces/current/members` | List members |-| `PUT` | `/api/v1/workspaces/current/members/{id}` | Update member role |-| `DELETE` | `/api/v1/workspaces/current/members/{id}` | Remove member |-| `POST` | `/api/v1/workspaces/current/invitations` | Invite member |-| `GET` | `/api/v1/workspaces/current/invitations` | List invitations |-| `DELETE` | `/api/v1/workspaces/current/invitations/{id}` | Cancel invitation |-| `POST` | `/api/v1/workspaces/current/transfer` | Transfer personal data |-| `GET` | `/api/v1/invitations` | List my invitations |-| `POST` | `/api/v1/invitations/{id}/accept` | Accept invitation |-| `POST` | `/api/v1/invitations/{id}/decline` | Decline invitation |--All workspace management endpoints require the `X-Workspace-ID` header (except create, list, and invitation actions).+curl -X POST http://localhost:9000/api/v1/workspaces \+ -H "Authorization: Bearer <jwt>" \+ -H "Content-Type: application/json" \+ -d '{"name": "Acme Inc", "slug": "acme"}'+```++Response (`201`):++```json+{+ "data": {+ "id": 1,+ "name": "Acme Inc",+ "slug": "acme",+ "description": "",+ "owner_id": 42,+ "role": "owner",+ "is_personal": false,+ "created_at": "2026-05-31T10:00:00Z"+ }+}+```++Creating a workspace is subject to your plan's workspace quota; exceeding it returns `403`. Creating a duplicate slug returns `409`.++## Listing workspaces++```+GET /api/v1/workspaces+```++Returns every workspace the current user is a member of, including the personal space. Each entry carries the caller's `role` in that workspace and the `is_personal` flag.++## Get, update, and delete the current workspace++```+GET /api/v1/workspaces/current+PUT /api/v1/workspaces/current+DELETE /api/v1/workspaces/current+```++`PUT` accepts any subset of the following; empty fields are left unchanged:++```json+{+ "name": "Acme Corporation",+ "description": "Updated description",+ "default_language": "fr"+}+```++`DELETE` removes the workspace and returns `204`. The personal workspace cannot be deleted (`400`).++```bash+curl -X PUT http://localhost:9000/api/v1/workspaces/current \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{"description": "Updated description"}'+```diff --git a/docs/docs/workspaces/settings.md b/docs/docs/workspaces/settings.mdnew file mode 100644index 0000000..353ead7--- /dev/null+++ b/docs/docs/workspaces/settings.md@@ -0,0 +1,163 @@+---+sidebar_position: 3+title: Settings, Plan, and Audit Log+description: Operational workspace settings, plan limits, and the workspace audit trail+---++# Settings, Plan, and Audit Log++Each workspace has its own operational settings, an effective plan with sending limits, and an audit trail. All endpoints use JWT bearer authentication and require the `X-Posta-Workspace-Id` header.++:::note+These are the **operational** workspace settings and audit log, distinct from the per-user `/api/v1/users/me/settings` (personal notification preferences) and `/api/v1/users/me/audit-log` (personal security events).+:::++## Operational settings++### Get settings++```+GET /api/v1/workspaces/current/settings+```++Any member may read the settings.++```bash+curl -X GET http://localhost:9000/api/v1/workspaces/current/settings \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```++Response:++```json+{+ "data": {+ "id": 1,+ "workspace_id": 1,+ "timezone": "UTC",+ "default_sender_name": "",+ "default_sender_email": "",+ "webhook_retry_count": 3,+ "api_key_expiry_days": 90,+ "bounce_auto_suppress": true,+ "require_verified_domain": false,+ "created_at": "2026-05-31T10:00:00Z",+ "updated_at": "2026-05-31T10:00:00Z"+ }+}+```++| Field | Type | Default | Description |+|-------|------|---------|-------------|+| `timezone` | string | `UTC` | Display/reporting timezone for the workspace |+| `default_sender_name` | string | — | Default From name applied when none is given |+| `default_sender_email` | string | — | Default From address applied when none is given |+| `webhook_retry_count` | int | `3` | Number of delivery retries for outgoing webhooks |+| `api_key_expiry_days` | int | `90` | Default lifetime for newly created API keys |+| `bounce_auto_suppress` | bool | `true` | Auto-suppress recipients on hard bounce / complaint |+| `require_verified_domain` | bool | `false` | Require a verified sending domain before sending |++### Update settings++```+PUT /api/v1/workspaces/current/settings+```++Requires the **admin** level or higher (owner or admin). Every field is optional; only the fields you include are changed.++```json+{+ "timezone": "Europe/Paris",+ "default_sender_name": "Acme",+ "default_sender_email": "[email protected]",+ "webhook_retry_count": 5,+ "api_key_expiry_days": 30,+ "bounce_auto_suppress": true,+ "require_verified_domain": true+}+```++```bash+curl -X PUT http://localhost:9000/api/v1/workspaces/current/settings \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1" \+ -H "Content-Type: application/json" \+ -d '{"require_verified_domain": true}'+```++The full settings object is returned on success.++## Workspace plan++```+GET /api/v1/workspaces/current/plan+```++Returns the effective plan and limits for the active workspace. A workspace may have its own assigned plan; otherwise the default plan applies.++```json+{+ "data": {+ "id": 2,+ "name": "Pro",+ "description": "",+ "is_default": false,+ "is_active": true,+ "daily_rate_limit": 50000,+ "hourly_rate_limit": 5000,+ "max_attachment_size_mb": 25,+ "max_batch_size": 1000,+ "max_api_keys": 50,+ "max_domains": 25,+ "max_smtp_servers": 10,+ "max_workspaces": 10,+ "email_log_retention_days": 90,+ "created_at": "2026-01-01T00:00:00Z",+ "updated_at": "2026-01-01T00:00:00Z"+ }+}+```++A limit of `0` means unlimited. Plans themselves are managed by platform administrators; see the Admin Panel documentation.++## Workspace audit log++```+GET /api/v1/workspaces/current/audit-log+```++Returns the audit trail for the active workspace — events recorded with `category = audit` and scoped to this workspace. Requires the **admin** level or higher (owner or admin).++Query parameters:++| Parameter | Type | Default | Description |+|-----------|------|---------|-------------|+| `page` | int | `0` | Zero-based page index |+| `size` | int | `20` | Page size |+| `category` | string | — | Optional event category filter |++```bash+curl -X GET "http://localhost:9000/api/v1/workspaces/current/audit-log?page=0&size=20" \+ -H "Authorization: Bearer <jwt>" \+ -H "X-Posta-Workspace-Id: 1"+```++Each event has the following shape:++```json+{+ "id": 101,+ "category": "audit",+ "type": "member.role_updated",+ "workspace_id": 1,+ "actor_id": 42,+ "actor_name": "Ada Lovelace",+ "client_ip": "203.0.113.10",+ "message": "Updated role for member 7 to editor",+ "metadata": "{}",+ "created_at": "2026-05-31T10:05:00Z"+}+```++The response is paginated; results are wrapped in the standard pageable envelope.diff --git a/docs/sidebars.ts b/docs/sidebars.tsindex 6159b8a..55489ed 100644--- a/docs/sidebars.ts+++ b/docs/sidebars.ts@@ -23,6 +23,7 @@ const sidebars: SidebarsConfig = {'email-sending/scheduled-email','email-sending/attachments','email-sending/email-status',+ 'email-sending/email-verification',],},{@@ -33,6 +34,7 @@ const sidebars: SidebarsConfig = {'templates/creating-templates','templates/versioning','templates/localization',+ 'templates/languages','templates/stylesheets','templates/preview-and-test','templates/import-export',@@ -85,6 +87,15 @@ const sidebars: SidebarsConfig = {'contacts/contact-lists','contacts/bounce-handling','contacts/suppression-list',+ 'contacts/unsubscribe-lists',+ ],+ },+ {+ type: 'category',+ label: 'Tracking & Engagement',+ items: [+ 'tracking/overview',+ 'tracking/unsubscribe',],},{@@ -97,6 +108,15 @@ const sidebars: SidebarsConfig = {'webhooks/audit-log',],},+ {+ type: 'category',+ label: 'Inbound Email',+ items: [+ 'inbound/overview',+ 'inbound/receiving',+ 'inbound/managing',+ ],+ },{type: 'category',label: 'Analytics & Monitoring',@@ -112,6 +132,8 @@ const sidebars: SidebarsConfig = {label: 'Workspaces',items: ['workspaces/overview',+ 'workspaces/members-and-invitations',+ 'workspaces/settings',],},{