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
docs: update official Posta SDKs
Jonas Kanindaafa417a65878
diff --git a/README.md b/README.mdindex 3d23b9b..d987233 100644--- a/README.md+++ b/README.md@@ -5,7 +5,7 @@</p><p align="center">- Self-hosted email delivery & inbound platform for developers and teams+Self-hosted email platform for sending, receiving, and relaying email through a unified API and SMTP.</p><p align="center"><a href="#overview">Overview</a> ·diff --git a/docs/docs/sdks/go.md b/docs/docs/sdks/go.mdindex e8853e6..66f7b35 100644--- a/docs/docs/sdks/go.md+++ b/docs/docs/sdks/go.md@@ -6,7 +6,7 @@ description: Posta Go SDK# Go SDK-Official Go client for Posta, built with [kitoko](https://github.com/jkaninda/kitoko).+Official Go client for Posta, built on [okapi/client](https://github.com/jkaninda/okapi).## Installation@@ -31,7 +31,7 @@ import (func main() {client := posta.New("https://posta.example.com", "your-api-key")- resp, err := client.SendEmail(&posta.SendEmailRequest{+ resp, err := client.Emails.Send(&posta.SendEmailRequest{From: "[email protected]",To: []string{"[email protected]"},Subject: "Hello from Posta",@@ -47,7 +47,7 @@ func main() {## Send Template Email```go-resp, err := client.SendTemplateEmail(&posta.SendTemplateEmailRequest{+resp, err := client.Emails.SendTemplate(&posta.SendTemplateEmailRequest{Template: "welcome",To: []string{"[email protected]"},From: "[email protected]",@@ -61,7 +61,7 @@ resp, err := client.SendTemplateEmail(&posta.SendTemplateEmailRequest{## Batch Send```go-resp, err := client.SendBatch(&posta.BatchRequest{+resp, err := client.Emails.SendBatch(&posta.BatchRequest{Template: "newsletter",From: "[email protected]",Recipients: []posta.BatchRecipient{@@ -75,14 +75,14 @@ fmt.Printf("Sent: %d, Failed: %d\n", resp.Sent, resp.Failed)## Check Delivery Status```go-status, err := client.GetEmailStatus("email-uuid")+status, err := client.Emails.Status("email-uuid")fmt.Printf("Status: %s\n", status.Status)```## Error Handling```go-_, err := client.GetEmailStatus("invalid-uuid")+_, err := client.Emails.Status("invalid-uuid")if err != nil {var apiErr *posta.APIErrorif errors.As(err, &apiErr) {@@ -93,3 +93,43 @@ if err != nil {}}```++## Full API coverage++The client covers the whole Posta API through resource services on the client:++| Service | Covers |+|---------|--------|+| `Emails` | send, templated and batch sends, preview, verify, status, retry, list, get |+| `Templates` | templates, versions, localizations, preview, send-test, import/export |+| `Campaigns` | CRUD, send, pause, resume, cancel, duplicate, messages, analytics |+| `Subscribers`, `SubscriberLists` | CRUD, members, segments, opt-ins and opt-outs |+| `Domains`, `SMTPServers`, `SMTPCredentials` | sending infrastructure and DNS verification |+| `Webhooks` | endpoints, delivery logs, and `posta.VerifySignature` |+| `Forms`, `Messages`, `MessageFilters` | web forms and the submissions they collect |+| `Inbound` | received email, raw `.eml`, attachments |+| `Workspaces`, `APIKeys`, `Users`, `Admin` | tenant and platform administration |++See the [client README](https://github.com/goposta/posta-go) for the full list.++## Workspaces++Workspace-scoped endpoints resolve the active workspace from the+`X-Posta-Workspace-Id` header. A workspace-bound API key carries its workspace+already; an account-wide key or a user session must name one:++```go+client := posta.New(baseURL, apiKey, posta.WithWorkspace(42))+```++## Verifying webhooks++Posta signs each delivery with HMAC-SHA256 over the raw body. Verify it against+the exact bytes received:++```go+if !posta.VerifySignature(body, r.Header.Get(posta.SignatureHeader), secret) {+ http.Error(w, "bad signature", http.StatusUnauthorized)+ return+}+```diff --git a/docs/docs/sdks/overview.md b/docs/docs/sdks/overview.mdindex 110bd49..44b4b53 100644--- a/docs/docs/sdks/overview.md+++ b/docs/docs/sdks/overview.md@@ -6,24 +6,63 @@ description: Official Posta SDKs# Official SDKs-Posta provides official client libraries for four languages. All SDKs offer the same core functionality:+Posta provides official client libraries that cover the whole API, grouped by+resource:-| Method | Description |-|--------|-------------|-| `SendEmail` | Send a single email with HTML/text, attachments, and headers |-| `SendTemplateEmail` | Send an email using a pre-defined template |-| `SendBatch` | Send batch emails to multiple recipients |-| `GetEmailStatus` | Check delivery status by email UUID |+| Area | Covers |+|------|--------|+| Emails | send, templated and batch sends, preview, address verification, status, retry, list |+| Templates | templates, versions, localizations, preview, send-test, import and export |+| Campaigns | CRUD, send, pause, resume, cancel, duplicate, per-recipient messages, analytics |+| Subscribers and lists | CRUD, members, segments, opt-ins and opt-outs, bulk import |+| Suppressions and bounces | list, add, remove, record |+| Sending infrastructure | domains and DNS verification, SMTP servers, SMTP relay credentials |+| Webhooks | endpoints, delivery logs, and signature verification |+| Web forms | forms, embed snippets, submissions, replies, spam filters |+| Inbound email | list, get, retry, raw `.eml`, attachments |+| Analytics | volume, delivery and bounce trends, provider breakdown, dashboard stats |+| Workspaces | members, invitations, settings, SSO, audit log, data export and import, GDPR erasure |+| Account and platform admin | profile, 2FA, sessions, notifications; users, plans, shared servers, settings |## Available SDKs| Language | Package | Min Version ||----------|---------|-------------|| [Go](/docs/sdks/go) | `github.com/goposta/posta-go` | Go 1.25+ |+| [Node.js](https://github.com/goposta/posta-node) | `@goposta/posta` | Node 18+ |+| [Python](https://github.com/goposta/posta-python) | `posta` | Python 3.8+ || [PHP](/docs/sdks/php) | `goposta/posta-php` | PHP 8.1+ || [Java](/docs/sdks/java) | `com.github.goposta:posta-java` | Java 11+ || [.NET](/docs/sdks/dotnet) | `Posta` | .NET 10+ |+## Credentials++Most machine-facing endpoints authenticate with an API key. Account-level+endpoints (`/users/me/*`) and the platform admin surface accept only a user+session token — an API key is never a valid credential there, whatever scopes+it carries.++Workspace-scoped endpoints resolve the active workspace from the+`X-Posta-Workspace-Id` header. A workspace-bound API key carries its workspace+already; an account-wide key or a user session must name one.++## API key scopes++A key reaches only what its scopes allow:++| Scope | Grants |+|-------|--------|+| `send` | sending, verification, and subscriber-list opt-ins |+| `read` | reading emails, bounces, webhook deliveries, and workspace resources |+| `write` | mutating workspace resources |+| `webhooks` | managing webhook endpoints |+| `admin` | tenant administration: API keys, members, invitations, settings, SSO |+| `*` | every scope |++Note that `send` grants none of the others: a send-only key is confined to the+public send API. A 403 from an endpoint you expect to work usually means a+missing scope.+## Error HandlingAll SDKs provide typed API errors that include:diff --git a/examples/docker-compose-full.yml b/examples/docker-compose-full.ymlindex 1bac737..85e5513 100644--- a/examples/docker-compose-full.yml+++ b/examples/docker-compose-full.yml@@ -56,14 +56,6 @@ services:POSTA_REDIS_ADDR: "posta-redis:6379"POSTA_WORKER_CONCURRENCY: "10"POSTA_WORKER_MAX_RETRIES: "5"- # The worker serves /healthz, /readyz and /metrics on the same port as the- # server. They are separate containers, so the shared number never collides.- healthcheck:- test: ["CMD", "posta-healthcheck"]- interval: 30s- timeout: 5s- start_period: 10s- retries: 3depends_on:posta-db:condition: service_healthy