Skip to content

IrwantoCia/email-hooker

Repository files navigation

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.

About

Email hook using LLM

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages