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 official Posta SDKs

Jonas Kanindaafa417a65878
diff --git a/README.md b/README.md
index 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.md
index 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{
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]"},
@@ -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",
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.APIError
if 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.md
index 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 Handling
All SDKs provide typed API errors that include:
diff --git a/examples/docker-compose-full.yml b/examples/docker-compose-full.yml
index 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: 3
depends_on:
posta-db:
condition: service_healthy