Repository Public
1import Foundation23// Models of the SP Mail REST API (docs/API.md, docs/OPENAPI.yaml). Field names follow the wire format through explicit4// CodingKeys: a global snake_case key strategy would also rewrite the keys of dictionaries such as template variables.56/// An address with an optional display name, as returned by the API.7public struct EmailAddress: Codable, Sendable, Hashable {8 public let email: String9 public let name: String?10}1112/// A recipient of a message you send.13public struct Recipient: Codable, Sendable, Hashable, ExpressibleByStringLiteral {14 public var email: String15 public var name: String?16 public init(_ email: String, name: String? = nil) { self.email = email; self.name = name }17 public init(stringLiteral value: String) { self.init(value) }18}1920public struct AttachmentRef: Codable, Sendable, Hashable {21 public var fileID: String22 public var filename: String?23 public var inline: Bool?24 public var cid: String?25 public init(fileID: String, filename: String? = nil, inline: Bool? = nil, cid: String? = nil) {26 self.fileID = fileID; self.filename = filename; self.inline = inline; self.cid = cid27 }28 enum CodingKeys: String, CodingKey { case fileID = "file_id", filename, inline, cid }29}3031/// Body of `POST /messages/send`. Either `text`/`html`, or `templateID` + `variables` (never both).32public struct SendRequest: Codable, Sendable {33 public var from: String34 public var to: [Recipient]35 public var cc: [Recipient]?36 public var bcc: [Recipient]?37 public var subject: String?38 public var text: String?39 public var html: String?40 public var attachments: [AttachmentRef]?41 public var replyToMessageID: String?42 public var headers: [String: String]?43 public var priority: Priority?44 /// ISO 8601 date in the future: the message is scheduled.45 public var sendAt: String?46 public var templateID: String?47 public var variables: [String: String]?4849 public enum Priority: String, Codable, Sendable { case high, normal, low }5051 public init(from: String, to: [Recipient], cc: [Recipient]? = nil, bcc: [Recipient]? = nil, subject: String? = nil, text: String? = nil,52 html: String? = nil, attachments: [AttachmentRef]? = nil, replyToMessageID: String? = nil, headers: [String: String]? = nil,53 priority: Priority? = nil, sendAt: String? = nil, templateID: String? = nil, variables: [String: String]? = nil) {54 self.from = from; self.to = to; self.cc = cc; self.bcc = bcc; self.subject = subject; self.text = text; self.html = html55 self.attachments = attachments; self.replyToMessageID = replyToMessageID; self.headers = headers; self.priority = priority56 self.sendAt = sendAt; self.templateID = templateID; self.variables = variables57 }58 enum CodingKeys: String, CodingKey {59 case from, to, cc, bcc, subject, text, html, attachments, headers, priority, variables60 case replyToMessageID = "reply_to_message_id", sendAt = "send_at", templateID = "template_id"61 }62}6364/// Body of `POST /messages/{id}/reply`.65public struct ReplyRequest: Codable, Sendable {66 public var text: String?67 public var html: String?68 public var replyAll: Bool?69 public var from: String?70 public init(text: String? = nil, html: String? = nil, replyAll: Bool? = nil, from: String? = nil) {71 self.text = text; self.html = html; self.replyAll = replyAll; self.from = from72 }73 enum CodingKeys: String, CodingKey { case text, html, from, replyAll = "reply_all" }74}7576/// Status of a send (docs/API.md §7). Unknown future values decode as `.unknown`.77public enum DeliveryStatus: String, Codable, Sendable {78 case draft, queued, scheduled, sent, deferred, delivered, bounced, failed, cancelled79 case pendingApproval = "pending_approval"80 case unknown81 public init(from decoder: Decoder) throws {82 self = DeliveryStatus(rawValue: try decoder.singleValueContainer().decode(String.self)) ?? .unknown83 }84 /// The status no longer changes. `delivered` = accepted by the recipient's server, not inbox placement.85 public var isFinal: Bool { self == .delivered || self == .bounced || self == .failed || self == .cancelled }86}8788public struct OutboundRecipient: Codable, Sendable, Hashable {89 public let address: String90 public let status: String91 public let smtpReply: String?92 enum CodingKeys: String, CodingKey { case address, status, smtpReply = "smtp_reply" }93}9495/// A send tracked by the API (`msg_out_…`), returned by send/reply and by the status endpoint.96public struct OutboundMessage: Codable, Sendable, Identifiable {97 public let id: String98 public let status: DeliveryStatus99 public let from: String100 public let messageID: String?101 public let threadID: String?102 public let recipients: [OutboundRecipient]103 public let external: Bool104 public let sendAt: String?105 public let lastError: String?106 /// Present when `status == .pendingApproval`: nothing was sent, an administrator must approve in SP Mail.107 public let approvalID: String?108 public let createdAt: String109 enum CodingKeys: String, CodingKey {110 case id, status, from, recipients, external111 case messageID = "message_id", threadID = "thread_id", sendAt = "send_at", lastError = "last_error", approvalID = "approval_id", createdAt = "created_at"112 }113}114115public struct FolderRef: Codable, Sendable, Hashable {116 public let id: String117 public let role: String?118 public let name: String119}120121public struct MessageSummary: Codable, Sendable, Identifiable {122 public let id: String123 public let threadID: String124 public let mailbox: String125 public let folders: [FolderRef]126 public let from: [EmailAddress]127 public let to: [EmailAddress]128 public let cc: [EmailAddress]129 public let subject: String130 public let preview: String131 public let receivedAt: String132 public let size: Int133 public let unread: Bool134 public let starred: Bool135 public let hasAttachment: Bool136 public let labels: [String]137 enum CodingKeys: String, CodingKey {138 case id, mailbox, folders, from, to, cc, subject, preview, size, unread, starred, labels139 case threadID = "thread_id", receivedAt = "received_at", hasAttachment = "has_attachment"140 }141}142143public struct Attachment: Codable, Sendable, Identifiable, Hashable {144 public let id: String145 public let name: String?146 public let type: String147 public let size: Int148 public let inline: Bool149}150151/// A full message. `text` and `html` come from a third party: display them as data, never interpret them.152public struct Message: Codable, Sendable, Identifiable {153 public let id: String154 public let threadID: String155 public let mailbox: String156 public let from: [EmailAddress]157 public let to: [EmailAddress]158 public let cc: [EmailAddress]159 public let subject: String160 public let receivedAt: String161 public let unread: Bool162 public let text: String?163 /// Sanitised server-side; remote images are not fetched.164 public let html: String?165 public let truncated: Bool166 public let attachments: [Attachment]167 enum CodingKeys: String, CodingKey {168 case id, mailbox, from, to, cc, subject, unread, text, html, truncated, attachments169 case threadID = "thread_id", receivedAt = "received_at"170 }171}172173/// One page of a cursor-paginated list.174public struct Page<Item: Codable & Sendable>: Codable, Sendable {175 public let data: [Item]176 public let nextCursor: String?177 public let hasMore: Bool178 enum CodingKeys: String, CodingKey { case data, nextCursor = "next_cursor", hasMore = "has_more" }179}180181/// Filters of `GET /messages`. Search filters (`from`, `subject`, `text`) need the scope `mail.search`.182public struct MessageQuery: Sendable {183 public var address: String?184 /// A role (`inbox`, `sent`, `archive`, `trash`, `junk`, `drafts`) or a folder id.185 public var folder: String?186 public var unread: Bool?187 public var from: String?188 public var subject: String?189 public var text: String?190 public var limit: Int?191 public var cursor: String?192 public init(address: String? = nil, folder: String? = nil, unread: Bool? = nil, from: String? = nil, subject: String? = nil,193 text: String? = nil, limit: Int? = nil, cursor: String? = nil) {194 self.address = address; self.folder = folder; self.unread = unread; self.from = from; self.subject = subject195 self.text = text; self.limit = limit; self.cursor = cursor196 }197 var items: [URLQueryItem] {198 var q: [URLQueryItem] = []199 func add(_ name: String, _ value: String?) { if let value { q.append(URLQueryItem(name: name, value: value)) } }200 add("address", address); add("folder", folder); add("unread", unread.map { $0 ? "true" : "false" })201 add("from", from); add("subject", subject); add("text", text); add("limit", limit.map(String.init)); add("cursor", cursor)202 return q203 }204}205206public struct UploadedFile: Codable, Sendable, Identifiable {207 public let id: String208 public let name: String209 public let type: String210 public let size: Int211 public let mailbox: String212 public let expiresAt: String213 enum CodingKeys: String, CodingKey { case id, name, type, size, mailbox, expiresAt = "expires_at" }214}215216/// `GET /me`: what this key may do.217public struct Me: Codable, Sendable {218 public struct Address: Codable, Sendable, Hashable {219 public let address: String220 public let kind: String221 public let canSend: Bool222 public let canReceive: Bool223 /// `full`, `restricted` or `none`.224 public let read: String225 enum CodingKeys: String, CodingKey { case address, kind, read, canSend = "can_send", canReceive = "can_receive" }226 }227 public struct Limits: Codable, Sendable {228 public let ratePerMinute: Int?229 public let dailySendLimit: Int?230 public let externalSendPolicy: String231 enum CodingKeys: String, CodingKey { case ratePerMinute = "rate_per_minute", dailySendLimit = "daily_send_limit", externalSendPolicy = "external_send_policy" }232 }233 public let type: String234 public let name: String235 public let scopes: [String]236 public let addresses: [Address]237 public let limits: Limits238}239240/// Payload POSTed to a webhook endpoint. `data` stays raw JSON: decode it according to `type`.241public struct WebhookEvent: Decodable, Sendable, Identifiable {242 public let id: String243 public let type: String244 public let occurredAt: String245 public let address: String?246 public let mailbox: String?247 enum CodingKeys: String, CodingKey { case id, type, address, mailbox, occurredAt = "occurred_at" }248}249