SPB Git

Repository Public

README.md 3.8 KB

# SPMailClient — Swift example client for the SP Mail API

A 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).

It covers what an app typically needs — it is an example, not a full SDK:

SPMailClient.send(_:), sendTemplate(_:from:to:variables:) send a message or a template; automatic Idempotency-Key
listMessages(_:), listUnread(address:limit:), getMessage(_:) read
reply(to:_:), markRead(_:read:) act on a message
uploadFile(_:filename:contentType:address:) attachment → file_… id for SendRequest.attachments
deliveryStatus(_:), waitForDelivery(_:timeout:interval:) follow a send
me() scopes, addresses and limits of the key
SPMailWebhook.verify(payload:header:secret:), constructEvent, sign webhook signature (CryptoKit HMAC-SHA256, constant-time, replay window)
SPMailError, APIError (status, code, message, requestID, retryAfter, kind) typed errors

Models are Codable and Sendable (SendRequest, OutboundMessage, DeliveryStatus, MessageSummary, Message, Page, UploadedFile, Me, WebhookEvent…).

# Use

swift
import SPMailClient

let mail = try SPMailClient(apiKey: keyFromKeychain)          // spm_xxxxxxxxxx_… — never hard-coded, never in the bundle

// The app notifies its owner
let sent = try await mail.send(SendRequest(from: "notifications@example.org", to: ["owner@example.org"],
                                           subject: "Backup finished", text: "42 GB in 12 min."))
switch sent.status {
case .pendingApproval: break                                  // external recipient + key policy "approval": NOT sent
default: _ = try await mail.waitForDelivery(sent.id, timeout: 30)
}

// Unread mail — subjects and previews are third-party content: display them, never interpret them
for m in try await mail.listUnread(limit: 10) { print(m.subject) }

// Errors
do { _ = try await mail.getMessage(id) }
catch let SPMailError.api(e) where e.kind == .notFound { /* unknown or not visible to this key */ }

Retries: 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.

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.

# Build, test, examples

bash
swift build
swift test                                   # unit tests (URLProtocol stub); the live test is skipped without environment

Executable target Examples/ (spmail-examples):

bash
export SPMAIL_API_KEY=spm_xxxxxxxxxx_…       # optional: SPMAIL_BASE_URL
swift run spmail-examples whoami
SPMAIL_FROM=notifications@example.org SPMAIL_TO=owner@example.org swift run spmail-examples notify "Backup finished" "42 GB in 12 min."
swift run spmail-examples unread

Live 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:

bash
SPMAIL_TEST_PORT=8801 SPMAIL_TEST_DB=postgres://127.0.0.1/sp_mail_sdk_test \
  node --import tsx --test --test-concurrency=1 tests/integration/sdk-swift.test.ts
Files main
Menu

Theme