Documentation
¶
Index ¶
- Constants
- 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 GetContactsCachePath() (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, provider, 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
- func (c *Config) AddAccount(account Account)
- func (c *Config) GetAccountByEmail(email string) *Account
- func (c *Config) GetAccountByID(id string) *Account
- func (c *Config) GetDateFormat() string
- func (c *Config) GetFirstAccount() *Account
- func (c *Config) HasAccounts() bool
- func (c *Config) RemoveAccount(id string) bool
- type Contact
- type ContactsCache
- type Draft
- type DraftsCache
- type EmailBodyCache
- type EmailCache
- type FolderCache
- type FolderEmailCache
- type MailingList
Constants ¶
const ( DateFormatISO = "YYYY-MM-DD HH:MM" DateFormatUS = "MM/DD/YYYY hh:MM AM" DateFormatEU = "DD/MM/YYYY HH:MM" )
Date format presets use human-readable tokens. Supported tokens:
YYYY (4-digit year), YY (2-digit year) MM (month, or minutes when following an hour token + colon) mm (minutes, explicit) DD (day) HH (24-hour), hh (12-hour, zero-padded) SS, ss (seconds) AM, PM (meridiem marker)
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 GetContactsCachePath ¶ added in v0.33.0
GetContactsCachePath returns the full path to the contacts cache file.
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 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. provider should be "gmail" or "outlook". If empty, the script auto-detects from the email. 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", "outlook", "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"`
IsCalendarInvite bool `json:"is_calendar_invite,omitempty"`
CalendarData []byte `json:"calendar_data,omitempty"` // Raw .ics data for calendar invites
}
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"`
DateFormat string `json:"date_format,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) GetDateFormat ¶ added in v0.33.0
GetDateFormat returns the Go time reference layout translated from the user's configured human-readable format. Defaults to EU when unset.
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.