📧✨ Beautiful email. For everyone.
export type View = 'inbox' | 'starred' | 'archive' | 'sent' | 'drafts' | 'junk' | 'trash' | 'all'
export type ConnectionState = 'connecting' | 'connected' | 'offline' | 'authentication' | 'error'
/** How an account's avatar looks: a generated marble pattern, or a picture the user chose. */
export interface AccountAppearance {
/** Varies the generated pattern; the account's address stands in until the user shuffles. */
seed?: string
/** A small square picture kept on this device, as a data URL. */
image?: string
}
/** Colours for the generated account avatars, tuned to sit calmly on dark and light surfaces. */
export const avatarColors = ['#4b3fb5', '#a69aef', '#e7ae7c', '#d491ac', '#7caee4']
/** Tuned to read well as text and as a soft tint in both themes. */
export const accountColors = [
'#a3a3ad',
'#a69aef',
'#7caee4',
'#6fc0cc',
'#83bba8',
'#d9bd6a',
'#e7ae7c',
'#d491ac',
'#e58f8f',
] as const
/** The first palette colour no other account uses, so new accounts stay distinguishable. */
export function nextAccountColor(used: string[]): string {
const taken = new Set(used.map((c) => c.toLowerCase()))
const free = accountColors.slice(1).find((c) => !taken.has(c))
return free || accountColors[1 + (used.length % (accountColors.length - 1))]
}
export interface Account {
id: string
connectionId: string
remoteId: string
/** A private label shown only in this app, never sent to anyone. */
name: string
email: string
/** The name recipients see in the From header; falls back to the server identity's name. */
senderName?: string
/**
* Other addresses this account may send from, such as aliases set up with the provider. Only
* IMAP accounts keep them here; JMAP servers list their own identities.
*/
aliases?: Alias[]
color: string
seed?: string
image?: string
status: ConnectionState
/** Why incoming mail is unavailable, when it is. */
error?: string
/** Set when the outgoing server rejected its login; incoming mail can still work. */
outgoingError?: string
sessionOnly?: boolean
/** Absent on records saved before IMAP support, which were always JMAP. */
protocol?: Protocol
/** Actions this server cannot perform safely, each with an explanation to show instead. */
limits?: AccountLimits
/** Present while the local index is still catching up with the server. */
indexing?: IndexingProgress
}
/** An address the provider delivers to this account and lets it send from. */
export interface Alias {
/** Identifies the alias as a sending identity, so drafts and signatures follow it. */
id: string
email: string
/** The name recipients see; falls back to the account's sender name. */
name?: string
}
/** An alias to save; one without an ID is new. */
export type AliasInput = Omit<Alias, 'id'> & { id?: string }
export interface AccountLimits {
move?: string
destroy?: string
}
export interface IndexingProgress {
indexed: number
/** Messages the server reports; can grow while indexing. */
total: number
complete: boolean
}
export interface Mailbox {
id: string
accountId: string
name: string
role: string | null
parentId: string | null
totalEmails: number
unreadEmails: number
rights: {
mayReadItems: boolean
mayAddItems: boolean
mayRemoveItems: boolean
maySetSeen: boolean
maySetKeywords: boolean
mayCreateChild: boolean
mayRename: boolean
mayDelete: boolean
}
}
export interface Address {
name: string
email: string
}
export interface Attachment {
blobId: string
name: string
type: string
size: number
cid?: string
disposition?: string
}
export interface MailSecurity {
encrypted: boolean
state: 'decrypted' | 'locked' | 'missingKey' | 'integrityFailure' | 'signed'
signature: 'valid' | 'invalid' | 'unknown' | 'unsigned'
fingerprint?: string
confirmed: boolean
detail?: string
}
export interface Message {
id: string
accountId: string
threadId: string
subject: string
from: Address[]
to: Address[]
cc: Address[]
bcc: Address[]
replyTo: Address[]
receivedAt: string
sentAt?: string
preview: string
keywords: Record<string, boolean>
mailboxIds: Record<string, boolean>
size: number
hasAttachment: boolean
html?: string
text?: string
attachments?: Attachment[]
messageId?: string[]
inReplyTo?: string[]
references?: string[]
unsubscribe?: { url: string; oneClick: boolean }
security?: MailSecurity
/** Revision of ciphertext, never a decrypted-body fingerprint. */
protectedRevision?: string
encryptionIntent?: boolean
/** Derived from this message after decryption; never persisted separately. */
authCandidate?: { type: 'code' | 'link'; value: string }
}
export interface Conversation {
id: string
accountId: string
key: string
subject: string
from: Address[]
preview: string
receivedAt: string
unread: boolean
starred: boolean
hasAttachment: boolean
count: number
messages: Message[]
}
export interface Identity {
id: string
accountId: string
name: string
email: string
mayDelete?: boolean
textSignature?: string
htmlSignature?: string
}
export interface MailQuery {
view: View
accountId?: string
mailboxId?: string
text?: string
from?: string
to?: string
subject?: string
after?: string
before?: string
hasAttachment?: boolean
unread?: boolean
}
export interface QueryPage {
items: Conversation[]
next?: Record<string, number>
total: number
failedAccounts: string[]
/** Accounts whose local index is still catching up; their results may be partial. */
incompleteAccounts?: string[]
}
export interface StagedAttachment {
id: string
name: string
type: string
size: number
blobId?: string
cid?: string
}
export interface Draft {
id: string
accountId: string
identityId: string
to: Address[]
cc: Address[]
bcc: Address[]
subject: string
html: string
text: string
attachments: StagedAttachment[]
updatedAt: string
inReplyTo?: string[]
references?: string[]
replyThreadId?: string
serverId?: string
serverFingerprint?: string
encryption?: 'none' | 'encrypt' | 'sign'
encryptionRequired?: boolean
downgradeConfirmed?: boolean
earlierPlaintext?: boolean
status: 'local' | 'saving' | 'synced' | 'error' | 'sending' | 'uncertain' | 'sent'
error?: string
/** What kind of problem `error` describes, so the composer can offer the right recovery. */
errorKind?: DraftErrorKind
}
export type DraftErrorKind =
'conflict' | 'connection' | 'outgoingAuthentication' | 'certificate' | 'rejected'
export interface Settings {
theme: 'dark' | 'light' | 'system'
remoteImages: boolean
notifications: boolean
/** Copy fresh verification/reset codes and links on arrival, with a desktop notification. */
autoCopyAuth?: boolean
closeToTray: boolean
/** Use the system window frame instead of inlark's title bar, after restarting. */
systemTitleBar?: boolean
defaultAccountId?: string
signatures: Record<string, string>
/** Identities whose signature is HTML code rather than plain text, keyed like `signatures`. */
htmlSignatures?: Record<string, boolean>
/** Where the reader goes after a conversation leaves the current view. */
afterArchive?: 'next' | 'previous' | 'list'
/**
* Keyboard shortcuts changed from their defaults, by action. Each binding is a list of chords
* pressed in turn, such as `['Mod+K']` or `['G', 'I']`; an empty list turns a shortcut off.
*/
shortcuts?: Record<string, string[][]>
}
export const defaultSettings: Settings = {
theme: 'dark',
remoteImages: true,
notifications: true,
autoCopyAuth: true,
closeToTray: true,
systemTitleBar: false,
signatures: {},
}
export type MailAction =
| 'archive'
| 'trash'
| 'restore'
| 'spam'
| 'notSpam'
| 'read'
| 'unread'
| 'star'
| 'unstar'
| 'move'
| 'destroy'
export interface MutationTarget {
accountId: string
threadId: string
}
export interface MutationInput {
targets: MutationTarget[]
action: MailAction
mailboxId?: string
}
export interface MutationResult {
changed: number
failures: string[]
undoId?: string
}
export interface AccountDetails {
name: string
senderName: string
}
export type Protocol = 'jmap' | 'imap'
/** Implicit TLS from the first byte, or a plain connection that must upgrade with STARTTLS. */
export type TransportSecurity = 'tls' | 'starttls'
export interface ServerSettings {
host: string
port: number
security: TransportSecurity
username: string
/** A certificate the user chose to trust for this server, in addition to public authorities. */
certificate?: TrustedCertificate
}
/** Exactly one certificate, identified by its SHA-256 fingerprint. */
export interface TrustedCertificate {
/** Upper-case hex pairs separated by colons, as shown to the user. */
sha256: string
pem: string
}
/**
* Why a server's certificate isn't accepted. `changed` means it differs from the trusted one.
* `expired` and `notYetValid` can't be trusted at all.
*/
export type CertificateProblem =
'selfSigned' | 'unknownIssuer' | 'otherName' | 'changed' | 'expired' | 'notYetValid'
/** A certificate a server presented, read without signing in, for the user to review. */
export interface CertificateDetails extends TrustedCertificate {
problem: CertificateProblem
/** The common name, or else the organization, of the subject and issuer. */
subject: string
issuer: string
/** The host names and addresses the certificate is valid for. */
names: string[]
validFrom: string
validTo: string
}
export interface JmapConnectionConfig {
protocol: 'jmap'
serverUrl: string
username: string
}
export interface ImapConnectionConfig {
protocol: 'imap'
/** The account's own address. Aliases are kept on the account. */
email: string
incoming: ServerSettings
outgoing: ServerSettings
/** When true the outgoing server uses the incoming password. */
outgoingSameCredentials: boolean
}
export type ConnectionConfig = JmapConnectionConfig | ImapConnectionConfig
export type FolderRole = 'sent' | 'drafts' | 'archive' | 'junk' | 'trash'
export const folderRoles: FolderRole[] = ['sent', 'drafts', 'archive', 'junk', 'trash']
/** An existing folder for a role, or one inlark should create. `null` means none. */
export type FolderMappings = Partial<Record<FolderRole, { path: string; create?: boolean } | null>>
export interface FolderMappingReview {
folders: { path: string; name: string }[]
/**
* `server` came from the server's special-use flags, `user` from an earlier choice. `name`
* is only a guess from the folder's name and should be confirmed.
*/
mappings: Partial<Record<FolderRole, { path: string; source: 'server' | 'user' | 'name' } | null>>
}
export interface ConnectInput {
config: ConnectionConfig
password: string
/** Only used when the outgoing server has its own credentials. */
outgoingPassword?: string
name: string
senderName?: string
remember: boolean
connectionId?: string
folders?: FolderMappings
}
/** A saved connection as the renderer may see it: never includes passwords. */
export interface ConnectionSettings {
connectionId: string
name: string
config: ConnectionConfig
remember: boolean
folders?: FolderMappings
}
export type DiscoverySource =
'jmap-srv' | 'jmap-well-known' | 'autoconfig' | 'imap-srv' | 'directory'
export type DiscoveryCandidate =
| { protocol: 'jmap'; source: DiscoverySource; serverUrl: string; username: string }
| {
protocol: 'imap'
source: DiscoverySource
incoming: ServerSettings
outgoing: ServerSettings
/** The provider name from a configuration file, shown for recognition only. */
provider?: string
}
export interface DiscoveryResult {
email: string
domain: string
/** In order of preference; JMAP always precedes IMAP. */
candidates: DiscoveryCandidate[]
}
export interface ConnectionCheck {
ok: boolean
error?: string
/** The certificate that stopped the connection, when the user may be able to trust it. */
certificate?: CertificateDetails
}
export interface ConnectionTest {
incoming: ConnectionCheck
/** Absent for JMAP, which submits through the same connection. */
outgoing?: ConnectionCheck
folders?: FolderMappingReview
}
export interface ProviderCapabilities {
mail: boolean
submission: boolean
push: boolean
maxObjectsInGet: number
maxObjectsInSet: number
maxUploadSize: number
/** Attachments must be uploaded before a draft can reference them (JMAP blobs). */
blobUpload?: boolean
/** A message lives in exactly one folder, so adding a folder without removing one copies it. */
exclusiveMailboxes?: boolean
/** `client` means the app must file its own Sent copy after submission. */
sentCopy?: 'server' | 'client'
}
export interface ProviderPage {
items: Conversation[]
total: number
next?: number
/** The local index has not caught up yet, so this page may miss older mail. */
incomplete?: boolean
}
/**
* A provider-neutral change to one message. `true` adds a folder or keyword, `false` removes it.
* Each provider translates this into its own protocol operations.
*/
export interface MessageChange {
mailboxes?: Record<string, boolean>
keywords?: Record<string, boolean>
}
export type MessageChanges = Record<string, MessageChange>
/** A message ready for submission, persisted before any network send. */
export interface OutgoingMessage {
/** The RFC 5322 Message-ID, without angle brackets. Unique per send attempt. */
messageId: string
/** The server-side email, for providers that submit stored messages (JMAP). */
emailId?: string
/** Complete MIME without Bcc headers, for providers that transmit it themselves (SMTP). */
mime?: Uint8Array
envelope: { from: string; to: string[] }
}
export interface SubmissionOutcome {
accepted: string[]
rejected: { email: string; reason: string }[]
}
export interface ProviderEvent {
type: 'changed' | 'status' | 'indexing'
accountId?: string
state?: ConnectionState
message?: string
indexing?: IndexingProgress
/** Set for changes found by historical indexing, which must never notify. */
historical?: boolean
}
export interface MailProvider {
readonly capabilities: ProviderCapabilities
connect(): Promise<Account[]>
/** Signs in to the outgoing server without sending anything (SMTP providers only). */
verifyOutgoing?(): Promise<void>
/**
* Reads the certificate a server presents without signing in. Undefined when the certificate
* would be accepted or can't be read.
*/
inspectCertificate?(server: 'incoming' | 'outgoing'): Promise<CertificateDetails | undefined>
/** Releases resources asynchronously, e.g. closing a local index before its files are removed. */
close?(): Promise<void>
mailboxes(account: Account): Promise<Mailbox[]>
identities(account: Account): Promise<Identity[]>
query(
account: Account,
query: MailQuery,
position?: number,
limit?: number,
): Promise<ProviderPage>
conversation(account: Account, threadId: string): Promise<Message[]>
getStateToken(account: Account): string | undefined
update(
account: Account,
changes: MessageChanges,
destroy?: string[],
expectedState?: string,
): Promise<{ updated: string[]; failures: string[] }>
conversationMetadata(account: Account, threadIds: string[]): Promise<Message[]>
messages(account: Account, ids: string[], bodies?: boolean): Promise<Message[]>
folder(
account: Account,
operation: 'create' | 'rename' | 'delete',
id?: string,
name?: string,
parentId?: string,
): Promise<void>
upload(account: Account, data: Uint8Array, type: string): Promise<string>
download(account: Account, attachment: Attachment): Promise<Uint8Array>
rawMessage?(account: Account, messageId: string, maxBytes: number): Promise<Uint8Array>
/** Bounded recent header-only samples for Autocrypt, including messages without a key header. */
encryptionHints?(
account: Account,
email: string,
): Promise<{ message: Message; headers: Uint8Array }[]>
createDraft(
account: Account,
draft: Draft,
messageId?: string,
mime?: Uint8Array,
): Promise<string>
/** Builds or stores the message to send. Must not transmit anything to recipients. */
prepareSubmission(
account: Account,
draft: Draft,
messageId: string,
mime?: Uint8Array,
): Promise<OutgoingMessage>
/**
* Sends a prepared message once. Throws `submissionRejected` when nothing was accepted,
* `submissionUncertain` when the outcome is unknown, and other codes when sending never began.
*/
submit(account: Account, message: OutgoingMessage, identityId: string): Promise<SubmissionOutcome>
/** Whether the server proves this message was submitted. A Sent copy alone is not proof. */
submissionExists(account: Account, message: OutgoingMessage): Promise<boolean>
/**
* Files a Sent copy for providers that do not do so themselves. Returns `server` when a copy
* with the same Message-ID already exists. Throws `filingUncertain` when an append may have
* completed without confirmation.
*/
fileSentCopy?(account: Account, message: OutgoingMessage): Promise<'filed' | 'server'>
folderMappings?(account: Account): Promise<FolderMappingReview>
setFolderMappings?(account: Account, mappings: FolderMappings): Promise<FolderMappingReview>
subscribe(listener: (event: ProviderEvent) => void): () => void
dispose(): void
}
export type AppEvent =
| { type: 'encryption'; locked: boolean }
| { type: 'unread'; count: number }
| { type: 'changed'; accountId?: string }
| { type: 'accounts'; accounts: Account[] }
| { type: 'mailto'; url: string }
| { type: 'open'; accountId: string; threadId: string }
| { type: 'progress'; completed: number; total: number }
| { type: 'submissions'; submissions: SubmissionSummary[] }
| { type: 'update'; status: UpdateStatus }
export type UpdateStatus =
| { phase: 'idle' }
| { phase: 'downloading'; version: string; percent: number }
| { phase: 'ready'; version: string }
| { phase: 'manual'; version: string }
export interface SendResult {
status: 'sent' | 'partial' | 'uncertain'
message: string
/** `pending` means the message was sent but its Sent copy is not filed yet. */
sentCopy?: 'filed' | 'pending'
/** Recipients the server refused while accepting others. */
rejected?: Address[]
}
/** The state of a send that still needs the user's attention. Contains no message body. */
export interface SubmissionSummary {
draftId: string
accountId: string
subject: string
at: string
state: 'sent' | 'partial' | 'uncertain'
sentCopy?: 'pending' | 'uncertain' | 'failed'
rejected?: Address[]
error?: string
}
export interface Bootstrap {
accounts: Account[]
settings: Settings
secureStorage: boolean
demo: boolean
version: string
}
export interface EncryptionKeySummary {
fingerprint: string
email: string
sources: ('own' | 'import' | 'wkd' | 'autocrypt' | 'gossip')[]
confirmed: boolean
accepted: boolean
usable: boolean
problem?: string
publicKey: string
retired?: boolean
backup?: 'needed' | 'postponed' | 'done'
}
export interface EncryptionIdentity {
accountId: string
identityId: string
email: string
fingerprint: string
enabled: boolean
prefer: boolean
}
export interface EncryptionStatus {
vault: 'absent' | 'locked' | 'unlocked'
protection?: 'os' | 'password'
identities: EncryptionIdentity[]
keys: EncryptionKeySummary[]
}
export interface RecipientReadiness {
email: string
status: 'ready' | 'missing' | 'expired' | 'revoked' | 'unusable' | 'changed' | 'conflict'
fingerprint?: string
confirmed: boolean
prefers: boolean
}
export interface EncryptionReadiness {
senderReady: boolean
recipients: RecipientReadiness[]
recommend: boolean
}
export interface StartupPreferences {
enabled?: boolean
startMinimized?: boolean
}
export interface StartupStatus {
supported: boolean
enabled: boolean
startMinimized: boolean
requiresApproval: boolean
error?: string
}
export interface DesktopMailAPI {
startupStatus(): Promise<StartupStatus>
setStartup(preferences: StartupPreferences): Promise<StartupStatus>
encryptionStatus(): Promise<EncryptionStatus>
setupEncryption(input: {
accountId: string
identityId: string
action: 'create' | 'import' | 'replace' | 'historical'
password?: string
keyPassword?: string
importReplacement?: boolean
}): Promise<EncryptionStatus>
setEncryptionPreference(
accountId: string,
identityId: string,
enabled: boolean,
prefer: boolean,
): Promise<EncryptionStatus>
exportEncryptionKey(
fingerprint: string,
kind: 'public' | 'backup',
password?: string,
): Promise<void>
revokeEncryptionKey(fingerprint: string): Promise<EncryptionStatus>
postponeEncryptionBackup(fingerprint: string): Promise<EncryptionStatus>
discoverEncryptionKeys(email: string, refresh?: boolean): Promise<EncryptionKeySummary[]>
acceptEncryptionKey(
email: string,
fingerprint: string,
confirmed: boolean,
): Promise<EncryptionStatus>
encryptionReadiness(
accountId: string,
identityId: string,
recipients: string[],
): Promise<EncryptionReadiness>
unlockEncryption(password?: string): Promise<EncryptionStatus>
lockEncryption(): Promise<void>
transferEncryption(input: {
accountId: string
identityId: string
action: 'export' | 'import'
code?: string
password?: string
}): Promise<{ code?: string }>
bootstrap(): Promise<Bootstrap>
updateStatus(): Promise<UpdateStatus>
ready(): Promise<void>
discover(email: string): Promise<DiscoveryResult>
/** Checks a login without saving it. Nothing is sent to any recipient. */
testConnection(input: ConnectInput): Promise<ConnectionTest>
connect(input: ConnectInput): Promise<Account[]>
connectionSettings(connectionId: string): Promise<ConnectionSettings>
folderMappings(accountId: string): Promise<FolderMappingReview>
setFolderMappings(accountId: string, mappings: FolderMappings): Promise<FolderMappingReview>
disconnect(connectionId: string): Promise<void>
reconnect(connectionId: string): Promise<void>
updateAccount(accountId: string, appearance: AccountAppearance): Promise<Account[]>
updateAccountDetails(accountId: string, details: AccountDetails): Promise<Account[]>
/** Replaces an IMAP account's aliases. The provider must already deliver and accept them. */
setAliases(accountId: string, aliases: AliasInput[]): Promise<Account[]>
mailboxes(accountId: string): Promise<Mailbox[]>
identities(accountId: string): Promise<Identity[]>
query(query: MailQuery, cursor?: Record<string, number>): Promise<QueryPage>
conversation(accountId: string, threadId: string): Promise<Message[]>
mutate(input: MutationInput): Promise<MutationResult>
mutateAll(query: MailQuery, action: MailAction): Promise<MutationResult>
undo(id: string): Promise<MutationResult>
folder(input: {
accountId: string
operation: 'create' | 'rename' | 'delete'
id?: string
name?: string
parentId?: string
}): Promise<void>
drafts(): Promise<Draft[]>
resumeDraft(accountId: string, messageId: string): Promise<Draft>
stageRemoteAttachments(
accountId: string,
attachments: Attachment[],
protectedDraft?: boolean,
): Promise<StagedAttachment[]>
saveDraft(draft: Draft): Promise<Draft>
syncDraft(draft: Draft): Promise<Draft>
deleteDraft(id: string): Promise<void>
/** Deletes a draft that exists only on the server, such as one started in another client. */
deleteServerDraft(accountId: string, messageId: string): Promise<void>
send(draft: Draft): Promise<SendResult>
reconcile(draftId: string): Promise<SendResult>
submissions(): Promise<SubmissionSummary[]>
/** Retries only the Sent copy of a message that was already sent. */
retrySentCopy(draftId: string): Promise<SendResult>
/** Starts a new draft addressed only to the recipients a partial send refused. */
recoverRejected(draftId: string): Promise<Draft>
/** Starts a new draft from an unconfirmed send; the unconfirmed record is kept. */
replaceUncertain(draftId: string): Promise<Draft>
dismissSubmission(draftId: string): Promise<void>
stageAttachments(protectedDraft?: boolean): Promise<StagedAttachment[]>
attachment(accountId: string, attachment: Attachment, open: boolean): Promise<void>
inlineImage(accountId: string, attachment: Attachment): Promise<string>
remoteImage(url: string, userInitiated?: boolean): Promise<string | null>
senderAvatar(email: string): Promise<string | null>
unsubscribe(
accountId: string,
messageId: string,
): Promise<{ kind: 'done' | 'mailto' | 'browser'; url?: string }>
openExternal(url: string): Promise<void>
settings(settings: Settings): Promise<Settings>
restart(): Promise<void>
diagnostics(): Promise<string>
onEvent(listener: (event: AppEvent) => void): () => void
}