### Install goimapnotify

Source: https://gitlab.com/shackra/goimapnotify/-/blob/master/README.md

Installs the goimapnotify command-line tool using 'go install'. Ensure your Go environment is set up correctly.

```bash
go install gitlab.com/shackra/goimapnotify/cmd/goimapnotify@latest
```

--------------------------------

### Legacy JSON Configuration Example

Source: https://context7.com/shackra/goimapnotify/llms.txt

An example of the older, single-account JSON configuration format. Note the direct specification of mailboxes instead of a list.

```json
{
  "host": "imap.example.com",
  "port": 993,
  "tls": true,
  "tlsOptions": { "rejectUnauthorized": true, "starttls": false },
  "username": "user@example.com",
  "passwordCMD": "pass show mail/example",
  "onNewMail": "mbsync example:INBOX",
  "onNewMailPost": "notmuch new",
  "boxes": ["INBOX", "Drafts"]
}
```

--------------------------------

### Go IMAP Notify Configuration File Example

Source: https://context7.com/shackra/goimapnotify/llms.txt

An example of a YAML configuration file for goimapnotify, specifying IMAP accounts, credentials, mailboxes to watch, and shell commands to execute on events.

```yaml
# ~/.config/goimapnotify/goimapnotify.yaml
#

```

--------------------------------

### Managing goimapnotify Systemd User Services

Source: https://context7.com/shackra/goimapnotify/llms.txt

Commands to enable, start, view logs, and restart goimapnotify services for specific configurations. Use systemctl --user for user-level services.

```bash
# Enable and start for the "gmail" config (~/.config/imapnotify/gmail.yaml)
systemctl --user enable --now goimapnotify@gmail.service

# Enable and start for a second account
systemctl --user enable --now goimapnotify@work.service

# View live logs
journalctl --user -u goimapnotify@gmail.service -f

# Restart after editing the config
systemctl --user restart goimapnotify@gmail.service
```

--------------------------------

### Google OAuth2 Configuration for goimapnotify

Source: https://context7.com/shackra/goimapnotify/llms.txt

Configuration for Gmail using oauth2l to fetch access tokens. Ensure oauth2l is installed and configured with credentials.

```yaml
configurations:
    - 
        host: imap.gmail.com
        port: 993
        tls: true
        tlsOptions:
            rejectUnauthorized: true
            starttls: false
        username: user@gmail.com
        # oauth2l fetches a fresh access token and outputs it to stdout
        passwordCMD: "oauth2l fetch --credentials ~/.config/oauth2l/creds.json imap"
        xoAuth2: true
        boxes:
            - 
                mailbox: INBOX
                onNewMail: "mbsync gmail:INBOX"
                onNewMailPost: "notmuch new"
```

--------------------------------

### Office 365 OAuth2 Configuration for goimapnotify

Source: https://context7.com/shackra/goimapnotify/llms.txt

Configuration for Office 365/Exchange Online using oauth2ms. Ensure oauth2ms is installed and authenticated.

```yaml
configurations:
    - 
        host: outlook.office365.com
        port: 993
        tls: true
        tlsOptions:
            rejectUnauthorized: true
            starttls: false
        username: user@company.com
        passwordCMD: "oauth2ms"
        xoAuth2: true
        boxes:
            - 
                mailbox: Inbox
                onNewMail: "mbsync o365:Inbox"
```

--------------------------------

### Generate CHANGELOG with git-chglog

Source: https://gitlab.com/shackra/goimapnotify/-/blob/master/README.md

Command to generate the CHANGELOG using the git-chglog tool. It specifies the output file and the starting tag for generation.

```bash
git-chglog --output CHANGELOG.md 2.3.14
```

--------------------------------

### Go Template Support in Commands

Source: https://context7.com/shackra/goimapnotify/llms.txt

Utilize Go `text/template` syntax within command strings for dynamic configuration. Fields like `.Alias`, `.Mailbox`, and `.Reason` are available in the template context.

```yaml
# Available template fields:
#   .Alias          - account alias string
#   .Mailbox        - mailbox name that triggered the event
#   .Reason         - EventType (NEWMAIL, DELETEDMAIL, FLAGCHANGED, SYNC)
#   .ExistingEmail  - message count at time of event (int)

configurations:
    - 
        host: imap.fastmail.com
        port: 993
        tls: true
        tlsOptions:
            rejectUnauthorized: true
            starttls: false
        username: user@fastmail.com
        passwordCMD: "pass show mail/fastmail"
        boxes:
            - 
                # Use .Mailbox to pass the mailbox name dynamically
                mailbox: INBOX
                onNewMail: "mbsync fastmail:{{.Mailbox}}"
                onNewMailPost: "notmuch new && notify-send 'New mail in {{.Mailbox}} ({{.Alias}})'"
            - 
                mailbox: Archive
                onNewMail: "mbsync fastmail:{{.Mailbox}}"
                onNewMailPost: "SKIP"

# Legacy %s substitution (still supported) — replaced with mailbox name:
#   onNewMail: "mbsync fastmail:%s"

```

--------------------------------

### TLS Configuration Options for goimapnotify

Source: https://context7.com/shackra/goimapnotify/llms.txt

Reference for TLS settings including implicit TLS (IMAPS), STARTTLS upgrade, self-signed certificates, and plain connections.

```yaml
# Implicit TLS — most common
tlsOptions:
    rejectUnauthorized: true
    starttls: false

# STARTTLS — connects plain then upgrades
tlsOptions:
    rejectUnauthorized: true
    starttls: true

# Self-signed certificate (e.g., local Dovecot instance)
tlsOptions:
    rejectUnauthorized: false
    starttls: false
```

--------------------------------

### Systemd User Service for goimapnotify

Source: https://context7.com/shackra/goimapnotify/llms.txt

A parameterized systemd user service unit for running multiple goimapnotify instances. Ensure the service file is placed in /etc/systemd/user/.

```ini
# /etc/systemd/user/goimapnotify@.service  (installed at build time)
[Unit]
Description=Execute scripts on IMAP mailbox changes using IDLE, golang version.
StartLimitIntervalSec=1d
StartLimitBurst=5

[Service]
Type=simple
ExecStart=/usr/bin/goimapnotify -conf %h/.config/imapnotify/%i.yaml
Restart=always
RestartSec=30

[Install]
WantedBy=default.target
```

--------------------------------

### Configure Multiple IMAP Accounts

Source: https://context7.com/shackra/goimapnotify/llms.txt

Define connection details, credentials, and event handlers for multiple IMAP accounts. Use `passwordCMD` for secure password retrieval. Event handlers like `onNewMail` and `onNewMailPost` can be set globally or per mailbox.

```yaml
configurations:
    - 
        # --- Connection ---
        host: imap.gmail.com          # IMAP server hostname
        # hostCMD: secret-tool lookup host gmail  # alternatively, retrieve host from a command
        port: 993
        tls: true
        tlsOptions:
            rejectUnauthorized: true  # set false for self-signed certs
            starttls: false           # set true to use STARTTLS on plain port
        idleLogoutTimeout: 25         # minutes between IDLE command restarts (default 25)
        enableIDCommand: false        # send IMAP ID to server (some servers require it)

        # --- Credentials ---
        username: user@gmail.com
        # usernameCMD: secret-tool lookup username gmail
        password: ""
        passwordCMD: "secret-tool lookup password gmail"  # preferred over plain password
        xoAuth2: false                # set true to use OAuth2 Bearer / XOAUTH2

        # --- Optional human-readable alias (hides username in logs) ---
        alias: Gmail

        # --- Global event handlers (inherited by all boxes unless overridden) ---
        onNewMail:         "mbsync gmail:INBOX"
        onNewMailPost:     "notmuch new"
        onChangedMail:     "mbsync gmail:INBOX"
        onChangedMailPost: "SKIP"     # SKIP disables this handler
        onDeletedMail:     "mbsync gmail:INBOX"
        onDeletedMailPost: "SKIP"

        # --- Mailboxes to watch (omit to watch ALL mailboxes) ---
        boxes:
            - 
                mailbox: INBOX
                onNewMail: "mbsync gmail:INBOX"
                onNewMailPost: "notmuch new"
            - 
                mailbox: Junk
                onNewMail: "mbsync gmail:Junk"
                onNewMailPost: "SKIP"
            - 
                mailbox: "[Gmail]/Sent Mail"
                onNewMail: "mbsync gmail:sent"
                onChangedMail: "mbsync gmail:sent"

    - 
        # Second account — retrieve all credentials dynamically
        hostCMD:     "pass show mail/work/host"
        port: 143
        tls: true
        tlsOptions:
            rejectUnauthorized: true
            starttls: true            # STARTTLS on port 143
        usernameCMD: "pass show mail/work/user"
        passwordCMD: "pass show mail/work/pass"
        alias: Work
        # No boxes key → monitor every selectable mailbox
        onNewMail: "mbsync work"
        onNewMailPost: "notmuch new && afew --tag --new"

```

--------------------------------

### Go IMAP Notify CLI Flags

Source: https://context7.com/shackra/goimapnotify/llms.txt

Demonstrates various command-line flags for configuring goimapnotify's behavior, including configuration file path, logging level, mailbox listing, and event debounce delay.

```bash
goimapnotify -help
```

```bash
# Usage of goimapnotify:
#   -conf string
#         Configuration file, supported formats: json, yaml/yml, toml
#         (default "$XDG_CONFIG_HOME/goimapnotify/goimapnotify.yaml")
#   -dial-retry-attempts int
#         Number of attempts when connecting to an IMAP server,
#         using exponential backoff (default 5)
#   -list
#         List all mailboxes and exit
#   -log-level string
#         Change the logging level; possible values are:
#         error, warn, info, debug (default "info")
#   -wait int
#         Delay in seconds between the IDLE event and the execution
#         of the scripts (default 1)
```

```bash
goimapnotify -conf ~/.config/mymail/notify.yaml -log-level debug
```

```bash
goimapnotify -conf ~/.config/mymail/notify.yaml -list
```

```bash
goimapnotify -conf ~/.config/mymail/notify.yaml -wait 3 -dial-retry-attempts 10
```

--------------------------------

### Go IMAP Notify Usage Flags

Source: https://gitlab.com/shackra/goimapnotify/-/blob/master/README.md

Lists the available command-line flags for the goimapnotify tool. Use these flags to configure behavior such as the configuration file path, retry attempts, logging level, and mailbox listing.

```bash
Usage of goimapnotify:
  -conf string
        Configuration file, supported formats: json, yaml/yml, toml (default "$XDG_CONFIG_HOME/goimapnotify/goimapnotify.yaml")
  -dial-retry-attempts int
        Number of attempts when connecting to an IMAP server, using exponential backoff (default 5)
  -list
        List all mailboxes and exit
  -log-level string
        Change the logging level; possible values are: error, warn, info, debug (default "info")
  -wait int
        Delay in seconds between the IDLE event and the execution of the scripts (default 1)
```

--------------------------------

### YAML Configuration for Go IMAP Notify

Source: https://gitlab.com/shackra/goimapnotify/-/blob/master/README.md

This configuration defines how Go IMAP notify connects to IMAP servers and what actions to perform on mail events. It supports direct credentials or command execution for sensitive information.

```yaml
configurations:
    - 
        host: example.com
        port: 143
        tls: true
        tlsOptions:
            rejectUnauthorized: false
            starttls: true
        idleLogoutTimeout: 15
        username: USERNAME
        alias: ExampleCOM
        password: PASSWORD
        xoAuth2: false
        boxes:
            - 
                mailbox: INBOX
                onNewMail: 'mbsync examplecom:INBOX'
                onChangedMail: 'mbsync examplenet:INBOX'
                onChangedMailPost: SKIP
                onNewMailPost: SKIP
    - 
        hostCMD: COMMAND_TO_RETRIEVE_HOST
        port: 993
        tls: true
        tlsOptions:
            rejectUnauthorized: true
            starttls: true
        username: ''
        usernameCMD: ''
        password: ''
        passwordCMD: ''
        xoAuth2: false
        onNewMail: ''
        onNewMailPost: ''
        onChangedMail: ''
        onChangedMailPost: ''
        onDeletedMail: ''
        onDeletedMailPost: ''
        boxes:
            - 
                mailbox: INBOX
                onNewMail: 'mbsync examplenet:INBOX'
                onNewMailPost: SKIP
                onChangedMail: 'mbsync examplenet:INBOX'
            - 
                mailbox: Junk
                onNewMail: 'mbsync examplenet:Junk'
                onNewMailPost: SKIP
```

--------------------------------

### OAuth2 / XOAuth2 Authentication

Source: https://context7.com/shackra/goimapnotify/llms.txt

Enable OAuth2/XOAuth2 authentication by setting `xoAuth2: true`. Ensure your `passwordCMD` outputs a valid bearer token, which is refreshed on each connection.

```yaml
xoAuth2: true                # set true to use OAuth2 Bearer / XOAUTH2
```

--------------------------------

### List Mailboxes with goimapnotify

Source: https://gitlab.com/shackra/goimapnotify/-/blob/master/README.md

Use the '-list' flag with goimapnotify to display all available mailboxes on your IMAP server. This is useful for understanding your mail server's hierarchy.

```bash
goimapnotify -list
```

--------------------------------

### Skip Handlers in goimapnotify Configuration

Source: https://context7.com/shackra/goimapnotify/llms.txt

Set a command value to SKIP (case-sensitive) to disable a handler for a specific mailbox. This overrides account-level defaults.

```yaml
configurations:
    - 
        host: imap.example.com
        port: 993
        tls: true
        tlsOptions:
            rejectUnauthorized: true
            starttls: false
        username: user@example.com
        passwordCMD: "pass show mail/example"
        # Account-level fallback runs for all boxes unless overridden
        onNewMail: "mbsync example"
        onNewMailPost: "notmuch new"
        boxes:
            - 
                mailbox: INBOX
                # Inherits account-level onNewMail / onNewMailPost
            - 
                mailbox: Spam
                onNewMail: "mbsync example:Spam"
                onNewMailPost: "SKIP"  # do NOT run notmuch new for spam
            - 
                mailbox: Trash
                onNewMail:     "SKIP"  # ignore new messages in Trash entirely
                onNewMailPost: "SKIP"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.