emailhooker

README

Email Hooker

A Go library for polling Gmail, matching emails with LLM rules, and running your callbacks in a background worker.

Installation

go get github.com/IrwantoCia/email-hooker

Usage

package main

import (
    "context"
    "log"

    "github.com/IrwantoCia/email-hooker"
)

func main() {
    hooker, err := emailhooker.NewOpenAIHooker(emailhooker.OpenAIHookerConfig{
        GmailConfig: emailhooker.GmailConfig{
            ClientID:     "your-google-client-id",
            ClientSecret: "your-google-client-secret",
            RefreshToken: "your-google-refresh-token",
        },
        OpenAIConfig: emailhooker.OpenAIConfig{
            APIKey: "your-openai-api-key",
            Model:  "gpt-4o-mini",
        },
        PollInterval: "30s",
        Debug:        false,
        Rules: []emailhooker.Rule{
            {
                Name:        "invoice",
                Description: "Financial requests and invoice related emails",
                Fields: []emailhooker.Field{
                    {Name: "invoice_number", Description: "Invoice number mentioned in the email body", Required: true},
                },
                Callbacks: []emailhooker.Callback{
                    func(ctx context.Context, input emailhooker.CallbackInput) (any, error) {
                        log.Printf("invoice email: %s invoice_number=%s", input.Email.Subject, input.Fields["invoice_number"])
                        return nil, nil
                    },
                },
            },
        },
    })
    if err != nil {
        log.Fatalf("build hooker: %v", err)
    }

    if err := hooker.Start(context.Background()); err != nil {
        log.Fatalf("start hooker: %v", err)
    }

    select {}
}

Public API

• emailhooker.NewOpenAIHooker(...) builds a complete worker with bundled Gmail fetcher + OpenAI parser + cron scheduler.
• hooker.Start(ctx) starts background polling.
• hooker.Stop(ctx) gracefully stops the worker.
• hooker.State() reports current worker state (idle, processing, stopped).
• Rule callbacks run once per matched rule and receive CallbackInput containing the email, matched rule name, and extracted fields.
• Enable Debug: true in OpenAIHookerConfig to log fetch/parse/match/callback flow.
• Keep debug disabled in production when possible because logs can include email-derived metadata.

Runnable example

• See examples/basic/main.go for a complete runnable worker with graceful shutdown.
• Run it with:

GOOGLE_CLIENT_ID=... \
GOOGLE_CLIENT_SECRET=... \
GOOGLE_REFRESH_TOKEN=... \
OPENAI_API_KEY=... \
EMAIL_HOOKER_DEBUG=false \
go run ./examples/basic

Advanced composition

If you want lower-level control, you can wire the components manually:

• github.com/IrwantoCia/email-hooker/gmail
• github.com/IrwantoCia/email-hooker/parser
• github.com/IrwantoCia/email-hooker/scheduler

License

MIT License - see LICENSE for details.

Documentation

Index

• Constants
• type Attachment
• type Callback
• type CallbackInput
• type Email
• type Field
• type GmailConfig
• type Hooker
  • func NewHooker(cfg HookerConfig) (Hooker, error)
  • func NewOpenAIHooker(cfg OpenAIHookerConfig) (Hooker, error)
• type HookerConfig
• type OpenAIConfig
• type OpenAIHookerConfig
• type Rule
• type RuleMatch
• type State

Constants

const (
	StateIdle       = base.StateIdle
	StateProcessing = base.StateProcessing
	StateStopped    = base.StateStopped
)

Types

type Attachment

type Attachment = base.Attachment

type Callback

type Callback = base.Callback

type CallbackInput

type CallbackInput = base.CallbackInput

type Email

type Email = base.Email

type Field

type Field = base.Field

type GmailConfig

type GmailConfig = publicgmail.Config

type Hooker

type Hooker interface {
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	State() State
}

func NewHooker

func NewHooker(cfg HookerConfig) (Hooker, error)

func NewOpenAIHooker

func NewOpenAIHooker(cfg OpenAIHookerConfig) (Hooker, error)

type HookerConfig

type HookerConfig struct {
	Scheduler       interfaces.Scheduler
	EmailFetcher    interfaces.EmailFetcher
	LLMParser       interfaces.LLMParser
	Rules           []Rule
	ParseTimeout    time.Duration
	CallbackTimeout time.Duration
	Debug           bool
	Logger          *log.Logger
}

type OpenAIConfig

type OpenAIConfig = publicparser.OpenAIConfig

type OpenAIHookerConfig

type OpenAIHookerConfig struct {
	GmailConfig     gmail.Config
	OpenAIConfig    parser.OpenAIConfig
	PollInterval    string
	Rules           []Rule
	SystemPrompt    string
	ParseTimeout    time.Duration
	CallbackTimeout time.Duration
	Debug           bool
	Logger          *log.Logger
}

type Rule

type Rule = base.Rule

type RuleMatch

type RuleMatch = base.RuleMatch

type State

type State = base.State