Documentation
¶
Index ¶
- func AddContact(name, email string) error
- func ClearEmailCache() error
- func ClearSessionKey()
- func Decrypt(ciphertext, key []byte) ([]byte, error)
- func DeleteDraft(id string) error
- func DeriveKey(password string, salt []byte) []byte
- func DisableSecureMode(cfg *Config) error
- func EnableSecureMode(password string, cfg *Config) error
- func Encrypt(plaintext, key []byte) ([]byte, error)
- func EnsurePGPDir() error
- func GetCacheDir() (string, error)
- func GetCachedFolders(accountID string) []string
- func GetConfigDir() (string, error)
- func GetOAuth2Token(email string) (string, error)
- func GetSessionKey() []byte
- func HasDrafts() bool
- func HasEmailCache() bool
- func HasSignature() bool
- func IsSecureModeEnabled() bool
- func LoadSignature() (string, error)
- func MigrateCacheFiles() error
- func OAuthScriptPath() (string, error)
- func PruneEmailBodyCache(folderName string, validUIDs map[uint32]string) error
- func RunOAuth2Flow(email, clientID, clientSecret string) error
- func SaveAccountFolders(accountID string, folders []string) error
- func SaveConfig(config *Config) error
- func SaveContactsCache(cache *ContactsCache) error
- func SaveDraft(draft Draft) error
- func SaveDraftsCache(cache *DraftsCache) error
- func SaveEmailBody(folderName string, body CachedEmailBody) error
- func SaveEmailCache(cache *EmailCache) error
- func SaveFolderCache(cache *FolderCache) error
- func SaveFolderEmailCache(folderName string, emails []CachedEmail) error
- func SaveSignature(signature string) error
- func SecureReadFile(path string) ([]byte, error)
- func SecureWriteFile(path string, data []byte, perm os.FileMode) error
- func SetSessionKey(key []byte)
- func VerifyPassword(password string) ([]byte, error)
- type Account
- func (a *Account) FormatFromHeader() string
- func (a *Account) GetFetchEmail() string
- func (a *Account) GetIMAPPort() int
- func (a *Account) GetIMAPServer() string
- func (a *Account) GetPOP3Port() int
- func (a *Account) GetPOP3Server() string
- func (a *Account) GetSMTPPort() int
- func (a *Account) GetSMTPServer() string
- func (a *Account) GetSendAsEmail() string
- func (a *Account) IsOAuth2() bool
- type CachedAttachment
- type CachedEmail
- type CachedEmailBody
- type CachedFolders
- type Config
- type Contact
- type ContactsCache
- type Draft
- type DraftsCache
- type EmailBodyCache
- type EmailCache
- type FolderCache
- type FolderEmailCache
- type MailingList
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddContact ¶ added in v0.8.0
AddContact adds or updates a contact in the cache.
func ClearEmailCache ¶ added in v0.8.0
func ClearEmailCache() error
ClearEmailCache removes the cache file.
func ClearSessionKey ¶ added in v0.32.0
func ClearSessionKey()
ClearSessionKey removes the session key from memory.
func DeleteDraft ¶ added in v0.8.0
DeleteDraft removes a draft by ID.
func DeriveKey ¶ added in v0.32.0
DeriveKey derives an AES-256 key from a password and salt using Argon2id.
func DisableSecureMode ¶ added in v0.32.0
DisableSecureMode decrypts all files back to plain JSON and removes secure.meta. The config must be passed so passwords can be restored to the OS keyring.
func EnableSecureMode ¶ added in v0.32.0
EnableSecureMode sets up encryption with the given password. It generates a salt, derives a key, encrypts the sentinel, saves secure.meta, and re-encrypts all existing data files. The config must be passed so that passwords (normally stored in the OS keyring) can be written into the encrypted config.
func Encrypt ¶ added in v0.32.0
Encrypt encrypts plaintext using AES-256-GCM. The nonce is prepended to the ciphertext.
func EnsurePGPDir ¶ added in v0.30.0
func EnsurePGPDir() error
EnsurePGPDir creates the PGP keys directory if it doesn't exist.
func GetCacheDir ¶ added in v0.32.0
GetCacheDir returns the path to the cache directory (exported).
func GetCachedFolders ¶ added in v0.22.0
GetCachedFolders returns cached folder names for a specific account.
func GetConfigDir ¶ added in v0.21.0
GetConfigDir returns the path to the configuration directory (exported).
func GetOAuth2Token ¶ added in v0.28.0
GetOAuth2Token retrieves a fresh OAuth2 access token for the account by invoking the Python helper script. The script handles token refresh automatically.
func GetSessionKey ¶ added in v0.32.0
func GetSessionKey() []byte
GetSessionKey returns the current session key, or nil if not set.
func HasDrafts ¶ added in v0.8.0
func HasDrafts() bool
HasDrafts checks if there are any saved drafts.
func HasEmailCache ¶ added in v0.8.0
func HasEmailCache() bool
HasEmailCache checks if a cache file exists.
func HasSignature ¶ added in v0.15.0
func HasSignature() bool
HasSignature checks if a signature file exists and is non-empty.
func IsSecureModeEnabled ¶ added in v0.32.0
func IsSecureModeEnabled() bool
IsSecureModeEnabled checks whether encryption is active by looking for secure.meta.
func LoadSignature ¶ added in v0.15.0
LoadSignature loads the signature from the signature file.
func MigrateCacheFiles ¶ added in v0.32.0
func MigrateCacheFiles() error
MigrateCacheFiles moves cache files from ~/.config/matcha/ to ~/.cache/matcha/ if needed. This is a one-time migration for existing installations.
func OAuthScriptPath ¶ added in v0.28.0
OAuthScriptPath returns the path to the Gmail OAuth2 Python helper script. The script is embedded in the binary and extracted to ~/.config/matcha/oauth/ on first use.
func PruneEmailBodyCache ¶ added in v0.32.0
PruneEmailBodyCache removes cached bodies for emails that are no longer in the folder. validUIDs is a map of UID -> AccountID for emails still present.
func RunOAuth2Flow ¶ added in v0.28.0
RunOAuth2Flow launches the OAuth2 authorization flow by invoking the Python helper script. It opens the user's browser for authorization. clientID and clientSecret are optional — if empty, the script uses stored credentials.
func SaveAccountFolders ¶ added in v0.22.0
SaveAccountFolders saves folder names for a specific account, merging into the existing cache.
func SaveConfig ¶
SaveConfig saves the given configuration to the config file and passwords to the keyring.
func SaveContactsCache ¶ added in v0.8.0
func SaveContactsCache(cache *ContactsCache) error
SaveContactsCache saves contacts to the cache file.
func SaveDraftsCache ¶ added in v0.8.0
func SaveDraftsCache(cache *DraftsCache) error
SaveDraftsCache saves drafts to the cache file.
func SaveEmailBody ¶ added in v0.32.0
func SaveEmailBody(folderName string, body CachedEmailBody) error
SaveEmailBody saves or updates a cached email body for a folder.
func SaveEmailCache ¶ added in v0.8.0
func SaveEmailCache(cache *EmailCache) error
SaveEmailCache saves emails to the cache file.
func SaveFolderCache ¶ added in v0.22.0
func SaveFolderCache(cache *FolderCache) error
SaveFolderCache saves the folder cache to disk.
func SaveFolderEmailCache ¶ added in v0.22.0
func SaveFolderEmailCache(folderName string, emails []CachedEmail) error
SaveFolderEmailCache saves emails for a folder to disk.
func SaveSignature ¶ added in v0.15.0
SaveSignature saves the signature to the signature file.
func SecureReadFile ¶ added in v0.32.0
SecureReadFile reads a file, decrypting it if a session key is set.
func SecureWriteFile ¶ added in v0.32.0
SecureWriteFile writes data to a file, encrypting it if a session key is set.
func SetSessionKey ¶ added in v0.32.0
func SetSessionKey(key []byte)
SetSessionKey stores the derived encryption key in memory for this session.
func VerifyPassword ¶ added in v0.32.0
VerifyPassword checks the password against the stored sentinel. Returns the derived key on success.
Types ¶
type Account ¶ added in v0.8.0
type Account struct {
ID string `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
Password string `json:"-"` // "-" prevents the password from being saved to config.json
ServiceProvider string `json:"service_provider"` // "gmail", "icloud", or "custom"
// FetchEmail is the single email address for which messages should be fetched.
// If empty, it will default to `Email` when accounts are added.
FetchEmail string `json:"fetch_email,omitempty"`
// SendAsEmail controls the visible From header on outgoing mail.
// If empty, it defaults to FetchEmail, then Email.
SendAsEmail string `json:"send_as_email,omitempty"`
// Custom server settings (used when ServiceProvider is "custom")
IMAPServer string `json:"imap_server,omitempty"`
IMAPPort int `json:"imap_port,omitempty"`
SMTPServer string `json:"smtp_server,omitempty"`
SMTPPort int `json:"smtp_port,omitempty"`
Insecure bool `json:"insecure,omitempty"`
// S/MIME settings
SMIMECert string `json:"smime_cert,omitempty"` // Path to the public certificate PEM
SMIMEKey string `json:"smime_key,omitempty"` // Path to the private key PEM
SMIMESignByDefault bool `json:"smime_sign_by_default,omitempty"` // Whether to enable S/MIME signing by default
// PGP settings
PGPPublicKey string `json:"pgp_public_key,omitempty"` // Path to public key (.asc or .gpg)
PGPPrivateKey string `json:"pgp_private_key,omitempty"` // Path to private key (.asc or .gpg)
PGPKeySource string `json:"pgp_key_source,omitempty"` // "file" (default) or "yubikey" for hardware key
PGPPIN string `json:"-"` // YubiKey PIN (stored in keyring, not JSON)
PGPSignByDefault bool `json:"pgp_sign_by_default,omitempty"` // Auto-sign outgoing emails
// OAuth2 settings
AuthMethod string `json:"auth_method,omitempty"` // "password" (default) or "oauth2"
// Multi-protocol settings
Protocol string `json:"protocol,omitempty"` // "imap" (default), "jmap", or "pop3"
JMAPEndpoint string `json:"jmap_endpoint,omitempty"` // JMAP session URL (for protocol=jmap)
POP3Server string `json:"pop3_server,omitempty"` // POP3 server hostname (for protocol=pop3)
POP3Port int `json:"pop3_port,omitempty"` // POP3 server port (for protocol=pop3)
}
Account stores the configuration for a single email account.
func (*Account) FormatFromHeader ¶ added in v0.32.0
FormatFromHeader returns the display-ready From header value.
func (*Account) GetFetchEmail ¶ added in v0.32.0
GetFetchEmail returns the configured fetch identity, falling back to Email.
func (*Account) GetIMAPPort ¶ added in v0.8.0
GetIMAPPort returns the IMAP port for the account.
func (*Account) GetIMAPServer ¶ added in v0.8.0
GetIMAPServer returns the IMAP server address for the account.
func (*Account) GetPOP3Port ¶ added in v0.29.0
GetPOP3Port returns the POP3 port for the account.
func (*Account) GetPOP3Server ¶ added in v0.29.0
GetPOP3Server returns the POP3 server address for the account.
func (*Account) GetSMTPPort ¶ added in v0.8.0
GetSMTPPort returns the SMTP port for the account.
func (*Account) GetSMTPServer ¶ added in v0.8.0
GetSMTPServer returns the SMTP server address for the account.
func (*Account) GetSendAsEmail ¶ added in v0.32.0
GetSendAsEmail returns the visible sender address for outgoing mail.
type CachedAttachment ¶ added in v0.32.0
type CachedAttachment struct {
Filename string `json:"filename"`
PartID string `json:"part_id"`
Encoding string `json:"encoding,omitempty"`
MIMEType string `json:"mime_type,omitempty"`
ContentID string `json:"content_id,omitempty"`
Inline bool `json:"inline,omitempty"`
IsSMIMESignature bool `json:"is_smime_signature,omitempty"`
SMIMEVerified bool `json:"smime_verified,omitempty"`
IsSMIMEEncrypted bool `json:"is_smime_encrypted,omitempty"`
}
CachedAttachment stores attachment metadata (not the binary data).
type CachedEmail ¶ added in v0.8.0
type CachedEmail struct {
UID uint32 `json:"uid"`
From string `json:"from"`
To []string `json:"to"`
Subject string `json:"subject"`
Date time.Time `json:"date"`
MessageID string `json:"message_id"`
AccountID string `json:"account_id"`
IsRead bool `json:"is_read"`
}
CachedEmail stores essential email data for caching.
func LoadFolderEmailCache ¶ added in v0.22.0
func LoadFolderEmailCache(folderName string) ([]CachedEmail, error)
LoadFolderEmailCache loads cached emails for a folder from disk.
type CachedEmailBody ¶ added in v0.32.0
type CachedEmailBody struct {
UID uint32 `json:"uid"`
AccountID string `json:"account_id"`
Body string `json:"body"`
Attachments []CachedAttachment `json:"attachments,omitempty"`
CachedAt time.Time `json:"cached_at"`
}
CachedEmailBody stores the body and attachment metadata for a single email.
func GetCachedEmailBody ¶ added in v0.32.0
func GetCachedEmailBody(folderName string, uid uint32, accountID string) *CachedEmailBody
GetCachedEmailBody returns the cached body for a specific email, or nil if not cached.
type CachedFolders ¶ added in v0.22.0
type CachedFolders struct {
AccountID string `json:"account_id"`
Folders []string `json:"folders"`
UpdatedAt time.Time `json:"updated_at"`
}
CachedFolders stores folder names for a single account.
type Config ¶
type Config struct {
Accounts []Account `json:"accounts"`
DisableImages bool `json:"disable_images,omitempty"`
HideTips bool `json:"hide_tips,omitempty"`
DisableNotifications bool `json:"disable_notifications,omitempty"`
Theme string `json:"theme,omitempty"`
MailingLists []MailingList `json:"mailing_lists,omitempty"`
}
Config stores the user's email configuration with multiple accounts.
func LoadConfig ¶
LoadConfig loads the configuration from the config file and passwords from the keyring. It automatically migrates plain-text passwords to the OS keyring if they exist.
func (*Config) AddAccount ¶ added in v0.8.0
AddAccount adds a new account to the configuration.
func (*Config) GetAccountByEmail ¶ added in v0.8.0
GetAccountByEmail returns an account by its email address.
func (*Config) GetAccountByID ¶ added in v0.8.0
GetAccountByID returns an account by its ID.
func (*Config) GetFirstAccount ¶ added in v0.8.0
GetFirstAccount returns the first account or nil if none exist.
func (*Config) HasAccounts ¶ added in v0.8.0
HasAccounts returns true if there are any configured accounts.
func (*Config) RemoveAccount ¶ added in v0.8.0
RemoveAccount removes an account by its ID and deletes its password from the keyring.
type Contact ¶ added in v0.8.0
type Contact struct {
Name string `json:"name"`
Email string `json:"email"`
LastUsed time.Time `json:"last_used"`
UseCount int `json:"use_count"`
}
Contact stores a contact's name and email address.
func SearchContacts ¶ added in v0.8.0
SearchContacts searches for contacts matching the query.
type ContactsCache ¶ added in v0.8.0
type ContactsCache struct {
Contacts []Contact `json:"contacts"`
UpdatedAt time.Time `json:"updated_at"`
}
ContactsCache stores all known contacts.
func LoadContactsCache ¶ added in v0.8.0
func LoadContactsCache() (*ContactsCache, error)
LoadContactsCache loads contacts from the cache file.
type Draft ¶ added in v0.8.0
type Draft struct {
ID string `json:"id"`
To string `json:"to"`
Cc string `json:"cc,omitempty"`
Bcc string `json:"bcc,omitempty"`
Subject string `json:"subject"`
Body string `json:"body"`
AttachmentPaths []string `json:"attachment_paths,omitempty"`
AccountID string `json:"account_id"`
InReplyTo string `json:"in_reply_to,omitempty"`
References []string `json:"references,omitempty"`
QuotedText string `json:"quoted_text,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
Draft stores a saved email draft.
func GetAllDrafts ¶ added in v0.8.0
func GetAllDrafts() []Draft
GetAllDrafts retrieves all drafts sorted by update time (newest first).
type DraftsCache ¶ added in v0.8.0
DraftsCache stores all saved drafts.
func LoadDraftsCache ¶ added in v0.8.0
func LoadDraftsCache() (*DraftsCache, error)
LoadDraftsCache loads drafts from the cache file.
type EmailBodyCache ¶ added in v0.32.0
type EmailBodyCache struct {
FolderName string `json:"folder_name"`
Bodies []CachedEmailBody `json:"bodies"`
UpdatedAt time.Time `json:"updated_at"`
}
EmailBodyCache stores cached email bodies for a folder.
func LoadEmailBodyCache ¶ added in v0.32.0
func LoadEmailBodyCache(folderName string) (*EmailBodyCache, error)
LoadEmailBodyCache loads the body cache for a folder.
type EmailCache ¶ added in v0.8.0
type EmailCache struct {
Emails []CachedEmail `json:"emails"`
UpdatedAt time.Time `json:"updated_at"`
}
EmailCache stores cached emails for all accounts.
func LoadEmailCache ¶ added in v0.8.0
func LoadEmailCache() (*EmailCache, error)
LoadEmailCache loads emails from the cache file.
type FolderCache ¶ added in v0.22.0
type FolderCache struct {
Accounts []CachedFolders `json:"accounts"`
UpdatedAt time.Time `json:"updated_at"`
}
FolderCache stores cached folders for all accounts.
func LoadFolderCache ¶ added in v0.22.0
func LoadFolderCache() (*FolderCache, error)
LoadFolderCache loads the folder cache from disk.
type FolderEmailCache ¶ added in v0.22.0
type FolderEmailCache struct {
FolderName string `json:"folder_name"`
Emails []CachedEmail `json:"emails"`
UpdatedAt time.Time `json:"updated_at"`
}
FolderEmailCache stores cached emails for a specific folder.
type MailingList ¶ added in v0.20.0
MailingList represents a named group of email addresses.