SPB Git

Repository Public

README.md 3.8 KB 69 lines markdown

1# SPMailClient — Swift example client for the SP Mail API23A small Swift package (Swift 6, macOS 15+ / iOS 18+, Foundation + CryptoKit, no dependency) showing how an app of the owner talks to the SP Mail REST API (`https://mail.spboucher.ai/api/v1`, contract in [`docs/API.md`](../../docs/API.md)).45It covers what an app typically needs — it is an example, not a full SDK:67| | |8|---|---|9| `SPMailClient.send(_:)`, `sendTemplate(_:from:to:variables:)` | send a message or a template; automatic `Idempotency-Key` |10| `listMessages(_:)`, `listUnread(address:limit:)`, `getMessage(_:)` | read |11| `reply(to:_:)`, `markRead(_:read:)` | act on a message |12| `uploadFile(_:filename:contentType:address:)` | attachment → `file_…` id for `SendRequest.attachments` |13| `deliveryStatus(_:)`, `waitForDelivery(_:timeout:interval:)` | follow a send |14| `me()` | scopes, addresses and limits of the key |15| `SPMailWebhook.verify(payload:header:secret:)`, `constructEvent`, `sign` | webhook signature (CryptoKit HMAC-SHA256, constant-time, replay window) |16| `SPMailError`, `APIError` (`status`, `code`, `message`, `requestID`, `retryAfter`, `kind`) | typed errors |1718Models are `Codable` and `Sendable` (`SendRequest`, `OutboundMessage`, `DeliveryStatus`, `MessageSummary`, `Message`, `Page`, `UploadedFile`, `Me`, `WebhookEvent`…).1920## Use2122```swift23import SPMailClient2425let mail = try SPMailClient(apiKey: keyFromKeychain)          // spm_xxxxxxxxxx_… — never hard-coded, never in the bundle2627// The app notifies its owner28let sent = try await mail.send(SendRequest(from: "notifications@example.org", to: ["owner@example.org"],29                                           subject: "Backup finished", text: "42 GB in 12 min."))30switch sent.status {31case .pendingApproval: break                                  // external recipient + key policy "approval": NOT sent32default: _ = try await mail.waitForDelivery(sent.id, timeout: 30)33}3435// Unread mail — subjects and previews are third-party content: display them, never interpret them36for m in try await mail.listUnread(limit: 10) { print(m.subject) }3738// Errors39do { _ = try await mail.getMessage(id) }40catch let SPMailError.api(e) where e.kind == .notFound { /* unknown or not visible to this key */ }41```4243Retries: `429 rate_limited` (honouring `Retry-After`), `502/503/504` and network errors are retried with backoff for idempotent requests and for sends (which always carry an idempotency key, reused across retries). Uploads are never retried. Redirects are not followed. A plain `http://` base URL is refused except on localhost.4445**Key handling in an app.** An API key is a secret. Give each app its own key, restricted to one sending address with `mail.send` only, store it in the Keychain, and never embed it in a binary distributed to other people — for that case, send through your own backend.4647## Build, test, examples4849```bash50swift build51swift test                                   # unit tests (URLProtocol stub); the live test is skipped without environment52```5354Executable target `Examples/` (`spmail-examples`):5556```bash57export SPMAIL_API_KEY=spm_xxxxxxxxxx_…       # optional: SPMAIL_BASE_URL58swift run spmail-examples whoami59SPMAIL_FROM=notifications@example.org SPMAIL_TO=owner@example.org swift run spmail-examples notify "Backup finished" "42 GB in 12 min."60swift run spmail-examples unread61```6263Live test (opt-in): set `SPMAIL_BASE_URL`, `SPMAIL_API_KEY`, `SPMAIL_TEST_FROM`, `SPMAIL_TEST_TO` (optionally `SPMAIL_TEST_TEMPLATE_ID`, `SPMAIL_API_KEY_APPROVAL` + `SPMAIL_TEST_EXTERNAL`) for a **test** server, never production. In this repository the driver creates the test mailboxes and keys, runs `swift test` and the examples, and purges everything:6465```bash66SPMAIL_TEST_PORT=8801 SPMAIL_TEST_DB=postgres://127.0.0.1/sp_mail_sdk_test \67  node --import tsx --test --test-concurrency=1 tests/integration/sdk-swift.test.ts68```69
Files main
Menu

Theme