Skip to content

armgit / posta

Public Imported from GitHub
0

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.

docs: update core features

Jonas Kanindad7968bbb1b05
diff --git a/docs/docs/admin/oauth-providers.md b/docs/docs/admin/oauth-providers.md
new file mode 100644
index 0000000..5dbadf0
--- /dev/null
+++ b/docs/docs/admin/oauth-providers.md
@@ -0,0 +1,137 @@
+---
+sidebar_position: 6
+title: OAuth Providers
+description: Configure OAuth / SSO providers for user authentication
+---
+
+# OAuth Providers
+
+Administrators can configure OAuth 2.0 / OpenID Connect providers to allow users to log in via single sign-on. Any OIDC-compliant identity provider is supported.
+
+:::tip
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
+:::
+
+## Supported Provider Types
+
+| Type | Description |
+|------|-------------|
+| `google` | Google OAuth 2.0 (pre-configured endpoints) |
+| `oidc` | Generic OpenID Connect (custom endpoints) |
+
+## Creating a Provider
+
+```
+POST /api/v1/admin/oauth/providers
+```
+
+### Google
+
+```json
+{
+ "name": "Google",
+ "slug": "google",
+ "type": "google",
+ "client_id": "your-google-client-id",
+ "client_secret": "your-google-client-secret",
+ "auto_register": true,
+ "allowed_domains": "example.com,company.org"
+}
+```
+
+### Generic OIDC (Keycloak, authentik, etc.)
+
+```json
+{
+ "name": "Keycloak",
+ "slug": "keycloak",
+ "type": "oidc",
+ "client_id": "posta",
+ "client_secret": "your-client-secret",
+ "issuer": "https://keycloak.example.com/realms/main",
+ "auth_url": "https://keycloak.example.com/realms/main/protocol/openid-connect/auth",
+ "token_url": "https://keycloak.example.com/realms/main/protocol/openid-connect/token",
+ "userinfo_url": "https://keycloak.example.com/realms/main/protocol/openid-connect/userinfo",
+ "scopes": "openid email profile",
+ "auto_register": true
+}
+```
+
+### Fields
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | Yes | — | Display name |
+| `slug` | Yes | — | URL-safe identifier (must be unique) |
+| `type` | Yes | — | `google` or `oidc` |
+| `client_id` | Yes | — | OAuth client ID |
+| `client_secret` | Yes | — | OAuth client secret |
+| `issuer` | No | — | OIDC issuer URL |
+| `auth_url` | No | — | Authorization endpoint (required for `oidc`) |
+| `token_url` | No | — | Token endpoint (required for `oidc`) |
+| `userinfo_url` | No | — | User info endpoint (required for `oidc`) |
+| `scopes` | No | `openid email profile` | OAuth scopes to request |
+| `auto_register` | No | `true` | Automatically create accounts for new users |
+| `allowed_domains` | No | — | Comma-separated list of allowed email domains |
+
+:::caution
+`client_id` and `client_secret` are never returned in API responses.
+:::
+
+## Listing Providers
+
+```
+GET /api/v1/admin/oauth/providers
+```
+
+## Updating a Provider
+
+```
+PUT /api/v1/admin/oauth/providers/{id}
+```
+
+All fields are optional.
+
+## Deleting a Provider
+
+```
+DELETE /api/v1/admin/oauth/providers/{id}
+```
+
+## Workspace SSO
+
+Workspace owners can enforce SSO for their workspace members by linking an OAuth provider.
+
+### Set Workspace SSO
+
+```
+PUT /api/v1/workspaces/current/sso
+```
+
+```json
+{
+ "provider_id": 1,
+ "enforce_sso": true,
+ "auto_provision": true,
+ "allowed_domains": "company.org"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `provider_id` | ID of the OAuth provider to use |
+| `enforce_sso` | When `true`, workspace members must log in via SSO |
+| `auto_provision` | Automatically add authenticated users as workspace members |
+| `allowed_domains` | Restrict access to specific email domains |
+
+### Get Workspace SSO
+
+```
+GET /api/v1/workspaces/current/sso
+```
+
+### Remove Workspace SSO
+
+```
+DELETE /api/v1/workspaces/current/sso
+```
diff --git a/docs/docs/admin/plans.md b/docs/docs/admin/plans.md
new file mode 100644
index 0000000..70daef6
--- /dev/null
+++ b/docs/docs/admin/plans.md
@@ -0,0 +1,120 @@
+---
+sidebar_position: 7
+title: Plans & Quotas
+description: Configure plans with rate limits and resource quotas
+---
+
+# Plans & Quotas
+
+Plans define resource limits and rate quotas for workspaces. Administrators can create plans with different tiers and assign them to workspaces.
+
+:::tip
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
+:::
+
+## Creating a Plan
+
+```
+POST /api/v1/admin/plans
+```
+
+```json
+{
+ "name": "Pro",
+ "description": "For growing teams",
+ "daily_rate_limit": 10000,
+ "hourly_rate_limit": 1000,
+ "max_attachment_size_mb": 25,
+ "max_batch_size": 500,
+ "max_api_keys": 20,
+ "max_domains": 10,
+ "max_smtp_servers": 5,
+ "max_workspaces": 3,
+ "email_log_retention_days": 90
+}
+```
+
+A value of `0` for any limit means **unlimited**.
+
+### Plan Fields
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `name` | — | Plan name (required, unique) |
+| `description` | — | Plan description |
+| `is_default` | `false` | Set as the default plan for new workspaces |
+| `daily_rate_limit` | `0` | Max emails per day |
+| `hourly_rate_limit` | `0` | Max emails per hour |
+| `max_attachment_size_mb` | `0` | Max attachment size in MB |
+| `max_batch_size` | `0` | Max recipients per batch email |
+| `max_api_keys` | `0` | Max API keys per workspace |
+| `max_domains` | `0` | Max verified domains per workspace |
+| `max_smtp_servers` | `0` | Max SMTP servers per workspace |
+| `max_workspaces` | `0` | Max workspaces per user |
+| `email_log_retention_days` | `0` | Days to retain email logs |
+
+## Listing Plans
+
+```
+GET /api/v1/admin/plans
+```
+
+## Getting a Plan
+
+```
+GET /api/v1/admin/plans/{id}
+```
+
+## Updating a Plan
+
+```
+PUT /api/v1/admin/plans/{id}
+```
+
+All fields are optional. Include `is_active` to enable or disable a plan.
+
+## Deleting a Plan
+
+```
+DELETE /api/v1/admin/plans/{id}?force=false
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `force` | `false` | If `true`, unassigns the plan from all workspaces before deletion. If `false` and the plan is assigned to workspaces, returns `409 Conflict`. |
+
+## Setting the Default Plan
+
+```
+PATCH /api/v1/admin/plans/{id}/default
+```
+
+The previous default plan (if any) is automatically unset.
+
+## Assigning a Plan to a Workspace
+
+```
+POST /api/v1/admin/workspaces/{id}/plan
+```
+
+```json
+{
+ "plan_id": 2
+}
+```
+
+## Viewing a Workspace's Plan
+
+### Admin View
+
+```
+GET /api/v1/admin/workspaces/{id}/plan
+```
+
+### User View
+
+```
+GET /api/v1/workspaces/current/plan
+```
+
+Returns the effective plan and limits for the current workspace.
diff --git a/docs/docs/admin/platform-settings.md b/docs/docs/admin/platform-settings.md
index de8b7f2..049f132 100644
--- a/docs/docs/admin/platform-settings.md
+++ b/docs/docs/admin/platform-settings.md
@@ -9,7 +9,7 @@ description: Configure platform-wide settings
Administrators can configure platform-wide settings that affect all users via the dashboard or `GET/PUT /api/v1/admin/settings`.
:::tip
-For the full request/response schema, see the interactive [Swagger](/swagger/index.html) or [ReDoc](/redoc) API documentation.
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
:::
## Available Settings
diff --git a/docs/docs/campaigns/ab-testing.md b/docs/docs/campaigns/ab-testing.md
new file mode 100644
index 0000000..4c20d68
--- /dev/null
+++ b/docs/docs/campaigns/ab-testing.md
@@ -0,0 +1,75 @@
+---
+sidebar_position: 3
+title: A/B Testing
+description: Test email variants with split audience campaigns
+---
+
+# A/B Testing
+
+Run A/B tests by splitting your subscriber list across multiple email variants. Compare performance to find the most effective subject line, content, or design.
+
+:::tip
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
+:::
+
+## Creating an A/B Test Campaign
+
+Enable A/B testing when creating a campaign:
+
+```json
+{
+ "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
+- Split percentages must sum to exactly **100**
+- Campaign must be in `draft` status to configure variants
+
+### Variant Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Variant identifier (e.g., "Variant A", "Short Subject") |
+| `split_percentage` | Percentage of the subscriber list that receives this variant |
+
+## How It Works
+
+When the campaign is sent, Posta randomly splits the subscriber list according to the configured percentages. Each subscriber receives exactly one variant.
+
+## Tracking Results
+
+Use the campaign analytics endpoint to compare variant performance:
+
+```
+GET /api/v1/users/me/campaigns/{id}/analytics
+```
+
+The response includes delivery stats broken down by variant, allowing you to compare open rates, click rates, and other metrics across variants.
+
+## Campaign Messages
+
+View individual messages sent for a campaign:
+
+```
+GET /api/v1/users/me/campaigns/{id}/messages?page=0&size=20
+```
+
+Each message includes which variant was sent to that subscriber.
diff --git a/docs/docs/campaigns/overview.md b/docs/docs/campaigns/overview.md
new file mode 100644
index 0000000..087e204
--- /dev/null
+++ b/docs/docs/campaigns/overview.md
@@ -0,0 +1,125 @@
+---
+sidebar_position: 1
+title: Overview
+description: Create and send email campaigns to subscriber lists
+---
+
+# Campaigns
+
+Campaigns let you send template-based emails to subscriber lists. They support scheduling, send rate control, A/B testing, and lifecycle management (pause, resume, cancel).
+
+:::tip
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
+:::
+
+## Creating a Campaign
+
+```
+POST /api/v1/users/me/campaigns
+```
+
+```json
+{
+ "name": "April Newsletter",
+ "subject": "What's new in April",
+ "from_email": "[email protected]",
+ "from_name": "Acme Team",
+ "template_id": 5,
+ "template_version_id": 12,
+ "language": "en",
+ "template_data": {
+ "month": "April",
+ "featured_url": "https://example.com/april"
+ },
+ "list_id": 3,
+ "send_rate": 100,
+ "scheduled_at": "2026-04-10T09:00:00Z"
+}
+```
+
+### Required Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Campaign name (internal reference) |
+| `subject` | Email subject line |
+| `from_email` | Sender email address |
+| `template_id` | Template to use for the email body |
+| `list_id` | Subscriber list to send to |
+
+### Optional Fields
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `from_name` | — | Sender display name |
+| `template_version_id` | — | Specific template version (uses active version if omitted) |
+| `language` | `en` | Template localization language |
+| `template_data` | — | Variables to pass to the template |
+| `send_rate` | `0` | Max emails per minute (`0` = unlimited) |
+| `send_at_local_time` | `false` | Send at scheduled time in each subscriber's local timezone |
+| `ab_test_enabled` | `false` | Enable A/B testing |
+| `ab_test_variants` | — | A/B test variant configuration |
+| `scheduled_at` | — | Schedule for future delivery |
+
+## Campaign Statuses
+
+| Status | Description |
+|--------|-------------|
+| `draft` | Initial state, can be edited |
+| `scheduled` | Scheduled for future delivery |
+| `sending` | Currently sending to subscribers |
+| `sent` | All messages delivered |
+| `paused` | Sending paused, can be resumed |
+| `cancelled` | Permanently cancelled |
+
+## Listing Campaigns
+
+```
+GET /api/v1/users/me/campaigns?page=0&size=20
+```
+
+Optional query parameters:
+
+| Parameter | Description |
+|-----------|-------------|
+| `page` | Page number (default: 0) |
+| `size` | Page size (default: 20) |
+| `status` | Filter by status |
+
+Response includes delivery stats for each campaign:
+
+```json
+{
+ "id": 1,
+ "name": "April Newsletter",
+ "status": "sending",
+ "stats": {
+ "total": 5000,
+ "pending": 2100,
+ "queued": 500,
+ "sent": 2300,
+ "failed": 50,
+ "skipped": 50
+ }
+}
+```
+
+## Getting a Campaign
+
+```
+GET /api/v1/users/me/campaigns/{id}
+```
+
+## Updating a Campaign
+
+```
+PUT /api/v1/users/me/campaigns/{id}
+```
+
+Only `draft` campaigns can be updated. All fields are optional.
+
+## Deleting a Campaign
+
+```
+DELETE /api/v1/users/me/campaigns/{id}
+```
diff --git a/docs/docs/campaigns/sending.md b/docs/docs/campaigns/sending.md
new file mode 100644
index 0000000..aa4791c
--- /dev/null
+++ b/docs/docs/campaigns/sending.md
@@ -0,0 +1,80 @@
+---
+sidebar_position: 2
+title: Sending & Lifecycle
+description: Send, pause, resume, and cancel campaigns
+---
+
+# Sending & Lifecycle
+
+Manage the full lifecycle of a campaign: send, pause, resume, cancel, and duplicate.
+
+:::tip
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
+:::
+
+## Sending a Campaign
+
+```
+POST /api/v1/users/me/campaigns/{id}/send
+```
+
+No request body required. The campaign transitions from `draft` to:
+
+- **`sending`** — if no `scheduled_at` is set or the scheduled time is in the past
+- **`scheduled`** — if `scheduled_at` is in the future
+
+Posta processes the subscriber list and queues individual emails for delivery. Each subscriber in the list receives one email.
+
+### Send Rate Control
+
+If `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.
+
+### Local Time Sending
+
+When `send_at_local_time` is `true` and `scheduled_at` is set, Posta delivers the campaign at the scheduled time in each subscriber's local timezone. Subscribers without a timezone receive the email at the scheduled UTC time.
+
+## Pausing a Campaign
+
+```
+POST /api/v1/users/me/campaigns/{id}/pause
+```
+
+Transitions a `sending` campaign to `paused`. Emails already queued will still be delivered, but no new emails are queued.
+
+## Resuming a Campaign
+
+```
+POST /api/v1/users/me/campaigns/{id}/resume
+```
+
+Transitions a `paused` campaign back to `sending`. Remaining subscribers will be processed.
+
+## Cancelling a Campaign
+
+```
+POST /api/v1/users/me/campaigns/{id}/cancel
+```
+
+Permanently cancels a campaign. Works from `sending`, `paused`, or `scheduled` states. Cancelled campaigns cannot be resumed.
+
+## Duplicating a Campaign
+
+```
+POST /api/v1/users/me/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.
+
+## Status Transitions
+
+```
+draft → sending (immediate send)
+draft → scheduled (future send)
+scheduled → sending (when scheduled time arrives)
+sending → paused
+paused → sending (resume)
+sending → cancelled
+paused → cancelled
+scheduled → cancelled
+sending → sent (all messages processed)
+```
diff --git a/docs/docs/email-sending/attachments.md b/docs/docs/email-sending/attachments.md
index c4dc1b5..0c1b7f2 100644
--- a/docs/docs/email-sending/attachments.md
+++ b/docs/docs/email-sending/attachments.md
@@ -9,7 +9,7 @@ description: Send emails with file attachments
Attach files to emails by providing base64-encoded content in the `attachments` array.
:::tip
-For the full request/response schema, see the interactive [Swagger](/swagger/index.html) or [ReDoc](/redoc) API documentation.
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
:::
## Example
diff --git a/docs/docs/email-sending/batch-email.md b/docs/docs/email-sending/batch-email.md
index 8943cd5..520716a 100644
--- a/docs/docs/email-sending/batch-email.md
+++ b/docs/docs/email-sending/batch-email.md
@@ -9,7 +9,7 @@ description: Send emails to multiple recipients efficiently
Send template-based emails to multiple recipients in a single API call, with per-recipient variable customization.
:::tip
-For the full request/response schema, see the interactive [Swagger](/swagger/index.html) or [ReDoc](/redoc) API documentation.
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
:::
## Example
diff --git a/docs/docs/email-sending/email-status.md b/docs/docs/email-sending/email-status.md
index b68d674..3ccda66 100644
--- a/docs/docs/email-sending/email-status.md
+++ b/docs/docs/email-sending/email-status.md
@@ -9,7 +9,7 @@ description: Track email delivery status
Check the delivery status of a sent email by its UUID.
:::tip
-For the full request/response schema, see the interactive [Swagger](/swagger/index.html) or [ReDoc](/redoc) API documentation.
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
:::
## Example
diff --git a/docs/docs/email-sending/single-email.md b/docs/docs/email-sending/single-email.md
index f324585..000a20f 100644
--- a/docs/docs/email-sending/single-email.md
+++ b/docs/docs/email-sending/single-email.md
@@ -9,7 +9,7 @@ description: Send a single email via the API
Send a single email with HTML/text content, optional attachments, custom headers, and scheduled delivery.
:::tip
-For the full request/response schema, see the interactive [Swagger](/swagger/index.html) or [ReDoc](/redoc) API documentation.
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
:::
## Example
diff --git a/docs/docs/email-sending/template-email.md b/docs/docs/email-sending/template-email.md
index 23c3382..fcf6fff 100644
--- a/docs/docs/email-sending/template-email.md
+++ b/docs/docs/email-sending/template-email.md
@@ -9,7 +9,7 @@ description: Send emails using pre-defined templates
Send emails using pre-defined templates with variable substitution and multi-language support.
:::tip
-For the full request/response schema, see the interactive [Swagger](/swagger/index.html) or [ReDoc](/redoc) API documentation.
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
:::
## Example
diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md
index b194f37..b839c75 100644
--- a/docs/docs/getting-started/installation.md
+++ b/docs/docs/getting-started/installation.md
@@ -8,48 +8,74 @@ description: Deploy Posta with Docker Compose or from source
Posta can be deployed using Docker Compose (recommended) or built from source.
-## Docker Compose (Recommended)
+:::tip
+Full Docker Compose examples are available in the [`examples/`](https://github.com/goposta/posta/tree/main/examples) folder of the repository.
+:::
-Create a `compose.yml` file:
+## Docker Compose — Embedded Worker (Simple)
+
+This setup runs Posta with the embedded worker enabled. The email processing worker runs inside the main server process, so no separate worker container is required. Ideal for development and small deployments.
+
+See [`examples/compose.yml`](https://github.com/goposta/posta/blob/main/examples/compose.yml)
```yaml
services:
posta:
- image: goposta/posta:latest
+ image: jkaninda/posta:latest
ports:
- "9000:9000"
environment:
- POSTA_DB_HOST: postgres
+ POSTA_DB_HOST: posta-db
+ POSTA_DB_NAME: posta
POSTA_DB_USER: posta
POSTA_DB_PASSWORD: posta
- POSTA_DB_NAME: posta
POSTA_DB_PORT: 5432
- POSTA_REDIS_ADDR: redis:6379
- POSTA_JWT_SECRET: change-me-in-production
- POSTA_ADMIN_EMAIL: [email protected]
- POSTA_ADMIN_PASSWORD: admin1234
+ POSTA_DB_SSL_MODE: disable
+ POSTA_REDIS_ADDR: "posta-redis:6379"
+ POSTA_JWT_SECRET: "change-me-in-production"
+ POSTA_ADMIN_EMAIL: "[email protected]"
+ POSTA_ADMIN_PASSWORD: "admin1234"
POSTA_EMBEDDED_WORKER: "true"
+ healthcheck:
+ test: ["CMD", "wget", "-qO-", "http://localhost:9000/healthz"]
+ interval: 30s
+ timeout: 5s
+ start_period: 10s
+ retries: 3
depends_on:
- - postgres
- - redis
-
- postgres:
- image: postgres:16-alpine
+ posta-db:
+ condition: service_healthy
+ posta-redis:
+ condition: service_healthy
+ restart: unless-stopped
+
+ posta-db:
+ image: postgres:17-alpine
environment:
POSTGRES_USER: posta
POSTGRES_PASSWORD: posta
POSTGRES_DB: posta
volumes:
- - pgdata:/var/lib/postgresql/data
-
- redis:
+ - db_data:/var/lib/postgresql/data
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U posta"]
+ interval: 5s
+ timeout: 5s
+ retries: 5
+
+ posta-redis:
image: redis:7-alpine
volumes:
- - redisdata:/data
+ - redis_data:/data
+ healthcheck:
+ test: ["CMD", "redis-cli", "ping"]
+ interval: 5s
+ timeout: 5s
+ retries: 5
volumes:
- pgdata:
- redisdata:
+ db_data:
+ redis_data:
```
Start the services:
@@ -60,6 +86,97 @@ docker compose up -d
Posta will be available at `http://localhost:9000`.
+## Docker Compose — Dedicated Worker (Production)
+
+For production environments, run the worker as a separate container. This allows the API server and background processing to scale independently.
+
+See [`examples/docker-compose-full.yml`](https://github.com/goposta/posta/blob/main/examples/docker-compose-full.yml)
+
+```yaml
+services:
+ posta:
+ image: jkaninda/posta:latest
+ ports:
+ - "9000:9000"
+ environment:
+ POSTA_DB_HOST: posta-db
+ POSTA_DB_NAME: posta
+ POSTA_DB_USER: posta
+ POSTA_DB_PASSWORD: posta
+ POSTA_DB_PORT: 5432
+ POSTA_DB_SSL_MODE: disable
+ POSTA_REDIS_ADDR: "posta-redis:6379"
+ POSTA_JWT_SECRET: "change-me-in-production"
+ POSTA_ADMIN_EMAIL: "[email protected]"
+ POSTA_ADMIN_PASSWORD: "admin1234"
+ healthcheck:
+ test: ["CMD", "wget", "-qO-", "http://localhost:9000/healthz"]
+ interval: 30s
+ timeout: 5s
+ start_period: 10s
+ retries: 3
+ depends_on:
+ posta-db:
+ condition: service_healthy
+ posta-redis:
+ condition: service_healthy
+ restart: unless-stopped
+
+ worker:
+ image: jkaninda/posta:latest
+ command: ["worker"]
+ environment:
+ POSTA_DB_HOST: posta-db
+ POSTA_DB_NAME: posta
+ POSTA_DB_USER: posta
+ POSTA_DB_PASSWORD: posta
+ POSTA_DB_PORT: 5432
+ POSTA_DB_SSL_MODE: disable
+ POSTA_REDIS_ADDR: "posta-redis:6379"
+ POSTA_WORKER_CONCURRENCY: "10"
+ POSTA_WORKER_MAX_RETRIES: "5"
+ depends_on:
+ posta-db:
+ condition: service_healthy
+ posta-redis:
+ condition: service_healthy
+ restart: unless-stopped
+
+ posta-db:
+ image: postgres:17-alpine
+ environment:
+ POSTGRES_USER: posta
+ POSTGRES_PASSWORD: posta
+ POSTGRES_DB: posta
+ volumes:
+ - db_data:/var/lib/postgresql/data
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U posta"]
+ interval: 5s
+ timeout: 5s
+ retries: 5
+
+ posta-redis:
+ image: redis:7-alpine
+ volumes:
+ - redis_data:/data
+ healthcheck:
+ test: ["CMD", "redis-cli", "ping"]
+ interval: 5s
+ timeout: 5s
+ retries: 5
+
+volumes:
+ db_data:
+ redis_data:
+```
+
+```bash
+docker compose -f docker-compose-full.yml up -d
+```
+
+You can run multiple worker instances for horizontal scaling. All workers share the same Redis queue.
+
## Build from Source
### Prerequisites
@@ -83,28 +200,16 @@ make build
./bin/posta server
```
-## Worker Deployment
-
-Posta processes emails asynchronously using background workers. You have two options:
-
-### Embedded Worker (Simple)
-
-Set `POSTA_EMBEDDED_WORKER=true` to run the worker within the API server process. This is the simplest setup for small deployments.
-
-### Standalone Worker (Scalable)
-
-For larger deployments, run the worker as a separate process:
+For standalone worker mode:
```bash
# API server
./bin/posta server
-# Worker (separate process/container)
+# Worker (separate process)
./bin/posta worker
```
-You can run multiple worker instances for horizontal scaling. All workers share the same Redis queue.
-
## Health Checks
Once running, verify the deployment:
diff --git a/docs/docs/getting-started/introduction.md b/docs/docs/getting-started/introduction.md
index cf4ebc9..3490839 100644
--- a/docs/docs/getting-started/introduction.md
+++ b/docs/docs/getting-started/introduction.md
@@ -19,17 +19,31 @@ description: What is Posta and why use it
| Feature | Description |
|---------|-------------|
-| **Email Delivery** | Send single, template, and batch emails via REST API |
-| **Templates** | Version-controlled templates with multi-language support |
-| **SMTP Management** | Configure multiple SMTP servers with automatic failover |
-| **Domain Verification** | SPF, DKIM, and DMARC record verification |
-| **Webhooks** | Real-time notifications on email events |
-| **Analytics** | Delivery rates, bounce rates, and latency metrics |
-| **Security** | API keys, JWT auth, 2FA (TOTP), rate limiting, IP allowlists |
-| **Admin Panel** | User management, platform metrics, shared SMTP pool |
+| **Email Delivery** | Send single, template, and batch emails via REST API with scheduled sending and automatic retries |
+| **Templates** | Version-controlled templates with multi-language support, variable substitution, and stylesheet inlining |
+| **SMTP Management** | Configure multiple SMTP servers with TLS support and shared pools |
+| **Domain Verification** | SPF, DKIM, and DMARC record verification with verified sender enforcement |
+| **Contacts & Suppression** | Contact tracking, segmentation, bounce handling, and automatic suppression lists |
+| **Subscribers & Lists** | Subscriber management with static and dynamic lists, bulk import, and custom fields |
+| **Campaigns** | Template-based bulk sending with scheduling, A/B testing, throttling, and analytics |
+| **Webhooks & Events** | Real-time HTTP notifications with retry strategies and delivery tracking |
+| **Analytics** | Email delivery metrics, trends, bounce rates, and daily reports |
+| **Security** | API keys, JWT auth, 2FA (TOTP), OAuth / SSO, rate limiting, IP allowlists |
+| **Workspaces** | Multi-tenant architecture with role-based access and scoped API keys |
+| **Admin Panel** | User management, platform metrics, shared SMTP pool, OAuth providers, and platform settings |
+| **Dashboard** | Vue-based web UI for managing all resources with dark/light mode |
| **GDPR Compliance** | Data export, import, and deletion |
| **Prometheus Metrics** | Built-in observability for production monitoring |
+## API Reference
+
+Posta provides interactive API documentation:
+
+- **Swagger UI** — [https://app.goposta.dev/docs](https://app.goposta.dev/docs)
+- **OpenAPI spec** — [https://app.goposta.dev/openapi.json](https://app.goposta.dev/openapi.json)
+
+When running locally, the docs are available at `/docs` on your Posta instance.
+
## Architecture
Posta is built with:
diff --git a/docs/docs/security/api-keys.md b/docs/docs/security/api-keys.md
index d2f0cf0..3800fd9 100644
--- a/docs/docs/security/api-keys.md
+++ b/docs/docs/security/api-keys.md
@@ -9,7 +9,7 @@ description: Create and manage API keys
API keys provide programmatic access to Posta's email sending and status APIs.
:::tip
-For the full request/response schema, see the interactive [Swagger](/swagger/index.html) or [ReDoc](/redoc) API documentation.
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
:::
## Creating a Key
diff --git a/docs/docs/security/authentication.md b/docs/docs/security/authentication.md
index a60a2b2..ae5b71c 100644
--- a/docs/docs/security/authentication.md
+++ b/docs/docs/security/authentication.md
@@ -73,6 +73,35 @@ Registration can be disabled via `POSTA_REGISTRATION_ENABLED=false`.
GET /api/v1/auth/registration-status
```
+## OAuth / SSO Authentication
+
+Posta supports OAuth 2.0 / OpenID Connect for single sign-on. Administrators can configure OAuth providers (Google, Keycloak, authentik, and others) from the Admin Panel under **OAuth**.
+
+Users can then log in via their identity provider without needing a Posta-specific password.
+
+### Supported Providers
+
+Any OAuth 2.0 / OIDC-compliant provider can be configured, including:
+
+- **Google**
+- **Keycloak**
+- **authentik**
+- Custom OIDC providers
+
+### OAuth Login Flow
+
+```
+GET /api/v1/auth/oauth/{provider}/authorize
+```
+
+Redirects the user to the provider's authorization page. After authentication, the provider redirects back to:
+
+```
+GET /api/v1/auth/oauth/callback?code=...&state=...
+```
+
+Posta exchanges the authorization code for user info and issues a JWT token.
+
## API Key Authentication (Programmatic)
API keys are used for sending emails and checking status via the API. See [API Keys](/docs/security/api-keys) for details on creating and managing keys.
diff --git a/docs/docs/smtp-domains/smtp-servers.md b/docs/docs/smtp-domains/smtp-servers.md
index d890185..353c040 100644
--- a/docs/docs/smtp-domains/smtp-servers.md
+++ b/docs/docs/smtp-domains/smtp-servers.md
@@ -9,7 +9,7 @@ description: Configure SMTP servers for email delivery
Configure one or more SMTP servers for email delivery. Posta routes emails through your configured SMTP servers.
:::tip
-For the full request/response schema, see the interactive [Swagger](/swagger/index.html) or [ReDoc](/redoc) API documentation.
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
:::
## Adding an SMTP Server
diff --git a/docs/docs/subscribers/bulk-import.md b/docs/docs/subscribers/bulk-import.md
new file mode 100644
index 0000000..7156ed1
--- /dev/null
+++ b/docs/docs/subscribers/bulk-import.md
@@ -0,0 +1,99 @@
+---
+sidebar_position: 2
+title: Bulk Import
+description: Import subscribers from JSON and CSV files
+---
+
+# Bulk Import
+
+Import subscribers in bulk using JSON or CSV formats.
+
+:::tip
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
+:::
+
+## JSON Import
+
+```
+POST /api/v1/users/me/subscribers/import/json
+```
+
+```json
+{
+ "subscribers": [
+ {
+ "email": "[email protected]",
+ "name": "Alice",
+ "timezone": "Europe/London",
+ "language": "en",
+ "custom_fields": {
+ "company": "Acme"
+ }
+ },
+ {
+ "email": "[email protected]",
+ "name": "Bob",
+ "language": "fr"
+ }
+ ]
+}
+```
+
+Response:
+
+```json
+{
+ "success": true,
+ "data": {
+ "created": 2,
+ "skipped": 0,
+ "total": 2
+ }
+}
+```
+
+Duplicate emails (already existing) are skipped, not updated.
+
+## CSV Import
+
+```
+POST /api/v1/users/me/subscribers/import/csv
+Content-Type: multipart/form-data
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `file` | Yes | CSV file |
+| `column_mapping` | No | JSON string mapping column indexes to fields |
+
+### Default Column Mapping
+
+If no `column_mapping` is provided:
+- Column 0 = `email`
+- Column 1 = `name`
+
+### Custom Column Mapping
+
+Map CSV columns to subscriber fields using a JSON object where keys are column indexes and values are field names:
+
+```json
+{
+ "0": "email",
+ "1": "name",
+ "2": "custom_fields.company",
+ "3": "custom_fields.role",
+ "4": "timezone",
+ "5": "language"
+}
+```
+
+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>" \
+ -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.md
new file mode 100644
index 0000000..b7315bd
--- /dev/null
+++ b/docs/docs/subscribers/subscriber-lists.md
@@ -0,0 +1,163 @@
+---
+sidebar_position: 3
+title: Subscriber Lists
+description: Organize subscribers into static and dynamic lists
+---
+
+# Subscriber Lists
+
+Subscriber lists group subscribers for use in campaigns. Lists can be **static** (manually managed) or **dynamic** (rule-based segments).
+
+:::tip
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
+:::
+
+## Creating a List
+
+```
+POST /api/v1/users/me/subscriber-lists
+```
+
+### Static List
+
+```json
+{
+ "name": "Newsletter Subscribers",
+ "description": "Users who opted in to the weekly newsletter",
+ "type": "static"
+}
+```
+
+### Dynamic List (Segment)
+
+```json
+{
+ "name": "Pro Users in US",
+ "description": "Subscribers with pro plan in US timezone",
+ "type": "dynamic",
+ "filter_rules": [
+ {
+ "field": "custom_fields.plan",
+ "operator": "equals",
+ "value": "pro"
+ },
+ {
+ "field": "timezone",
+ "operator": "contains",
+ "value": "America"
+ }
+ ]
+}
+```
+
+Dynamic lists automatically include all subscribers matching the filter rules. Membership is calculated at query time.
+
+## Listing Lists
+
+```
+GET /api/v1/users/me/subscriber-lists?page=0&size=20
+```
+
+Response includes `member_count` for each list.
+
+## Getting a List
+
+```
+GET /api/v1/users/me/subscriber-lists/{id}
+```
+
+## Updating a List
+
+```
+PUT /api/v1/users/me/subscriber-lists/{id}
+```
+
+All fields are optional.
+
+## Deleting a List
+
+```
+DELETE /api/v1/users/me/subscriber-lists/{id}
+```
+
+## Managing Members (Static Lists)
+
+### Add a Subscriber
+
+```
+POST /api/v1/users/me/subscriber-lists/{id}/members
+```
+
+```json
+{
+ "subscriber_id": 42
+}
+```
+
+Only works for static lists. Adding a subscriber to a dynamic list returns an error.
+
+### Remove a Subscriber
+
+```
+DELETE /api/v1/users/me/subscriber-lists/{id}/members
+```
+
+```json
+{
+ "subscriber_id": 42
+}
+```
+
+### List Members
+
+```
+GET /api/v1/users/me/subscriber-lists/{id}/members?page=0&size=20
+```
+
+## Preview Segment
+
+Test filter rules before creating a dynamic list:
+
+```
+POST /api/v1/users/me/subscriber-lists/preview-segment
+```
+
+```json
+{
+ "filter_rules": [
+ {
+ "field": "status",
+ "operator": "equals",
+ "value": "subscribed"
+ },
+ {
+ "field": "language",
+ "operator": "equals",
+ "value": "en"
+ }
+ ]
+}
+```
+
+Response:
+
+```json
+{
+ "success": true,
+ "data": {
+ "count": 1284
+ }
+}
+```
+
+## Filter Rules
+
+Each rule has three properties:
+
+| Property | Description |
+|----------|-------------|
+| `field` | Subscriber field to match (e.g., `status`, `language`, `timezone`, `custom_fields.plan`) |
+| `operator` | Comparison operator (`equals`, `contains`, etc.) |
+| `value` | Value to compare against |
+
+Filter rules are combined with AND logic — subscribers must match all rules to be included.
diff --git a/docs/docs/subscribers/subscriber-management.md b/docs/docs/subscribers/subscriber-management.md
new file mode 100644
index 0000000..02c70f0
--- /dev/null
+++ b/docs/docs/subscribers/subscriber-management.md
@@ -0,0 +1,101 @@
+---
+sidebar_position: 1
+title: Subscriber Management
+description: Create and manage email subscribers
+---
+
+# Subscriber Management
+
+Subscribers represent people who receive campaign emails. Each subscriber has an email, optional profile data, custom fields, and a status.
+
+:::tip
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
+:::
+
+## Creating a Subscriber
+
+```
+POST /api/v1/users/me/subscribers
+```
+
+```json
+{
+ "email": "[email protected]",
+ "name": "Jane Doe",
+ "status": "subscribed",
+ "timezone": "America/New_York",
+ "language": "en",
+ "custom_fields": {
+ "company": "Acme Inc",
+ "plan": "pro"
+ }
+}
+```
+
+Only `email` is required. Status defaults to `subscribed`.
+
+### Subscriber Statuses
+
+| Status | Description |
+|--------|-------------|
+| `subscribed` | Active subscriber, receives campaigns |
+| `unsubscribed` | Opted out, will not receive campaigns |
+| `bounced` | Email address bounced |
+| `complained` | Reported as spam |
+
+## Listing Subscribers
+
+```
+GET /api/v1/users/me/subscribers?page=0&size=20
+```
+
+Optional query parameters:
+
+| Parameter | Description |
+|-----------|-------------|
+| `page` | Page number (default: 0) |
+| `size` | Page size (default: 20) |
+| `search` | Search by email or name |
+| `status` | Filter by status |
+
+## Getting a Subscriber
+
+```
+GET /api/v1/users/me/subscribers/{id}
+```
+
+## Updating a Subscriber
+
+```
+PUT /api/v1/users/me/subscribers/{id}
+```
+
+```json
+{
+ "name": "Jane Smith",
+ "custom_fields": {
+ "company": "New Corp",
+ "plan": "enterprise"
+ }
+}
+```
+
+All fields are optional. When status changes to `unsubscribed`, the `unsubscribed_at` timestamp is set automatically.
+
+## Deleting a Subscriber
+
+```
+DELETE /api/v1/users/me/subscribers/{id}
+```
+
+## Custom Fields
+
+Subscribers support arbitrary key-value custom fields stored as JSON. These can be used for:
+
+- Personalization in campaign templates via `{{ .custom_fields.company }}`
+- Segmentation in dynamic subscriber lists
+- Filtering and search
+
+## Bulk Import
+
+See [Bulk Import](/docs/subscribers/bulk-import) for importing subscribers from JSON and CSV files.
diff --git a/docs/docs/webhooks/overview.md b/docs/docs/webhooks/overview.md
index 739ec91..ac7516f 100644
--- a/docs/docs/webhooks/overview.md
+++ b/docs/docs/webhooks/overview.md
@@ -9,7 +9,7 @@ description: Real-time webhooks for email events
Receive real-time HTTP notifications when email events occur. Posta sends POST requests to your configured URLs with event details.
:::tip
-For the full request/response schema, see the interactive [Swagger](/swagger/index.html) or [ReDoc](/redoc) API documentation.
+For the full request/response schema, see the interactive [API Reference](https://app.goposta.dev/docs).
:::
## Creating a Webhook
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
index 3213437..8a44496 100644
--- a/docs/docusaurus.config.ts
+++ b/docs/docusaurus.config.ts
@@ -61,7 +61,7 @@ const config: Config = {
label: 'Documentation',
},
{
- href: '/swagger/index.html',
+ href: 'https://app.goposta.dev/docs',
label: 'API Reference',
position: 'left',
},
@@ -84,7 +84,7 @@ const config: Config = {
title: 'Documentation',
items: [
{label: 'Getting Started', to: '/docs/getting-started/introduction'},
- {label: 'API Reference (Swagger)', href: '/swagger/index.html'},
+ {label: 'API Reference', href: 'https://app.goposta.dev/docs'},
{label: 'SDKs', to: '/docs/sdks/overview'},
],
},
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
index d81e890..cd4df6f 100644
--- a/docs/sidebars.ts
+++ b/docs/sidebars.ts
@@ -38,6 +38,24 @@ const sidebars: SidebarsConfig = {
'templates/import-export',
],
},
+ {
+ type: 'category',
+ label: 'Subscribers',
+ items: [
+ 'subscribers/subscriber-management',
+ 'subscribers/bulk-import',
+ 'subscribers/subscriber-lists',
+ ],
+ },
+ {
+ type: 'category',
+ label: 'Campaigns',
+ items: [
+ 'campaigns/overview',
+ 'campaigns/sending',
+ 'campaigns/ab-testing',
+ ],
+ },
{
type: 'category',
label: 'SMTP & Domains',
@@ -60,12 +78,12 @@ const sidebars: SidebarsConfig = {
},
{
type: 'category',
- label: 'Analytics & Monitoring',
+ label: 'Contacts & Suppression',
items: [
- 'analytics/dashboard',
- 'analytics/email-analytics',
- 'analytics/prometheus-metrics',
- 'analytics/health-checks',
+ 'contacts/contact-management',
+ 'contacts/contact-lists',
+ 'contacts/bounce-handling',
+ 'contacts/suppression-list',
],
},
{
@@ -80,12 +98,19 @@ const sidebars: SidebarsConfig = {
},
{
type: 'category',
- label: 'Contacts & Suppression',
+ label: 'Analytics & Monitoring',
items: [
- 'contacts/contact-management',
- 'contacts/contact-lists',
- 'contacts/bounce-handling',
- 'contacts/suppression-list',
+ 'analytics/dashboard',
+ 'analytics/email-analytics',
+ 'analytics/prometheus-metrics',
+ 'analytics/health-checks',
+ ],
+ },
+ {
+ type: 'category',
+ label: 'Workspaces',
+ items: [
+ 'workspaces/overview',
],
},
{
@@ -97,6 +122,8 @@ const sidebars: SidebarsConfig = {
'admin/platform-metrics',
'admin/shared-servers',
'admin/scheduled-jobs',
+ 'admin/oauth-providers',
+ 'admin/plans',
],
},
{
@@ -119,13 +146,8 @@ const sidebars: SidebarsConfig = {
},
{
type: 'link',
- label: 'API Reference (Swagger)',
- href: '/swagger/index.html',
- },
- {
- type: 'link',
- label: 'API Reference (ReDoc)',
- href: '/redoc',
+ label: 'API Reference',
+ href: 'https://app.goposta.dev/docs',
},
],
};
diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx
index 97bc67a..c6ad645 100644
--- a/docs/src/pages/index.tsx
+++ b/docs/src/pages/index.tsx
@@ -25,7 +25,7 @@ function HomepageHeader() {
<Link
className="button button--secondary button--outline button--lg"
style={{marginLeft: '1rem'}}
- href="/swagger/index.html">
+ href="https://app.goposta.dev/docs">
API Reference
</Link>
</div>