# agentmail

![license](https://img.shields.io/badge/license-MIT-blue)
![status](https://img.shields.io/badge/status-active-brightgreen)
![language](https://img.shields.io/badge/language-Go-00ADD8)
![version](https://img.shields.io/badge/version-0.1.0-orange)

> File-based message queue for local agent communication using Maildir

## table of contents

- [install](#install)
- [usage](#usage)
- [api](#api)
- [contributing](#contributing)
- [license](#license)

## install

```bash
go get github.com/yourusername/agentmail

usage

package main

import (
    "fmt"
    "log"
    
    "github.com/yourusername/agentmail"
)

func main() {
    // Create a new mailbox
    mbox, err := agentmail.NewMailbox("/var/spool/agents/myagent")
    if err != nil {
        log.Fatal(err)
    }
    defer mbox.Close()
    
    // Send a message
    msg := agentmail.Message{
        From: "agent1",
        To:   "agent2",
        Body: []byte("hello from agent1"),
    }
    
    if err := mbox.Send(msg); err != nil {
        log.Fatal(err)
    }
    
    // Receive messages
    messages, err := mbox.Receive()
    if err != nil {
        log.Fatal(err)
    }
    
    for _, m := range messages {
        fmt.Printf("From: %s\nBody: %s\n", m.From, string(m.Body))
        m.Delete() // Remove from queue after processing
    }
}

api

NewMailbox(path string) (*Mailbox, error)

Creates a new mailbox at the specified path. Creates the Maildir structure (new/, cur/, tmp/) if it doesn't exist.

(*Mailbox) Send(msg Message) error

Sends a message to the mailbox. Uses atomic file operations to ensure message integrity.

(*Mailbox) Receive() ([]*Message, error)

Retrieves all pending messages from the mailbox. Moves messages from new/ to cur/ following Maildir semantics.

(*Mailbox) Watch(handler func(*Message)) error

Watches the mailbox for new messages and calls the handler function for each one. Blocks until an error occurs or the context is canceled.

(*Message) Delete() error

Removes the message file from disk. Call after successfully processing a message.

(*Message) MarkRead() error

Updates the message filename to indicate it has been read.

Message struct

type Message struct {
    From      string
    To        string
    Timestamp time.Time
    Body      []byte
    Headers   map[string]string
}

contributing

prs welcome. open an issue first for big changes.

license

MIT