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
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
swift build
swift test # unit tests (URLProtocol stub); the live test is skipped without environmentExecutable target Examples/ (spmail-examples):
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 unreadLive 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:
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