📬 AgentBox — Agent in Your Inbox

AgentBox turns your email inbox into a smart AI-powered assistant.
It listens to incoming emails (via SendGrid Inbound Parse), analyzes the content, generates intelligent replies using OpenAI or Phronetic agents, and automatically sends responses — all while maintaining distinct personalities and prompts for each mailbox identity.

---

🚀 Features

• Email → AI → Reply Loop
  Receives inbound emails and auto-responds using OpenAI or Phronetic API.

• Per-Identity Personalization
  Each mailbox (e.g. agents@nhtech.link, recruitment@nhtech.link) has its own pre-prompt, post-prompt, CC address, and reply identity stored in Postgres.

• Dynamic Reply Identities
  Replies are sent from the identity that received the message.

• Stats Dashboard
  Tracks total emails processed, success/failure rates, average response time, and model usage.

• Simple REST API
  Manage agents, create/update their roles, and view system statistics.

• CORS-Enabled
  Ready for integration with any web dashboard or frontend.

---

🧠 System Overview

Incoming Email (SendGrid Inbound Webhook)
↓
FastAPI /inbound_email
↓
Extract email text
↓
Lookup identity settings (Postgres)
↓
Call OpenAI or Phronetic
↓
Compose + Send reply via SendGrid
↓
Log stats in Postgres

---

🧩 Tech Stack

Component	Technology
Backend API	FastAPI
AI Engine	OpenAI GPT-4o / Phronetic Agent API
Database	PostgreSQL
Email Handling	SendGrid Inbound Parse + Send API
HTTP Client	httpx
ORM / DB Layer	asyncpg
HTML Parsing	BeautifulSoup4
Environment	python-dotenv
Runtime	Uvicorn

---

⚙️ Installation & Setup

1. Clone the repository

git clone https://github.com/your-org/agentbox.git
cd agentbox

2. Create & activate virtual environment

python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Create a .env file

SENDGRID_API_KEY=your_sendgrid_key
OPENAI_API_KEY=your_openai_key
PHRONETIC_API_KEY=optional_phronetic_key
PHRONETIC_AGENT_ID=agnt_eb688b3b-60dd-49d4-966c-76edda72705e
DATABASE_URL=postgresql://user:password@localhost:5432/agentbox
REPLY_FROM=agents@nhtech.link
AI_MODEL=gpt-4o-mini

5. Initialize the database

Run these SQL migrations manually (or through a tool like pgAdmin):

CREATE TABLE agent_identity_prompts (
    id SERIAL PRIMARY KEY,
    identity_email VARCHAR(255) UNIQUE NOT NULL,
    job_role VARCHAR(255),
    description TEXT,
    pre_prompt TEXT,
    post_prompt TEXT,
    reply_from VARCHAR(255),
    cc_email VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE email_statistics (
    id SERIAL PRIMARY KEY,
    identity_email VARCHAR(255),
    sender_email VARCHAR(255),
    subject TEXT,
    model_used VARCHAR(100),
    used_phronetic BOOLEAN DEFAULT FALSE,
    success BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT NOW(),
    tokens_used INT DEFAULT 0,
    response_time_ms INT DEFAULT 0,
    error_message TEXT
);

---

▶️ Running the Server

Local Development

uvicorn main:app --reload

The API will be live at:

http://localhost:8000

---

🔗 API Endpoints

Endpoint	Method	Description
/inbound_email	POST	Handles SendGrid inbound webhook and generates AI replies
/agent_identity_prompts	POST	Creates a new agent (auto-generates prompts via OpenAI)
/stats	GET	Returns summary + recent activity metrics
/stats/{identity} (planned)	GET	View per-identity stats (future)

---

🧰 Example: Create a New Agent

curl -X POST "http://localhost:8000/agent_identity_prompts" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_email": "recruitment@nhtech.link",
    "job_role": "Recruitment Coordinator",
    "description": "Handles job applications, schedules interviews, and responds with empathy and professionalism.",
    "reply_from": "recruitment@nhtech.link",
    "cc_email": "hr@nhtech.link"
  }'

---

📊 Example: Fetch System Statistics

curl http://localhost:8000/stats

Response:

{
  "summary": {
    "total_emails": 47,
    "successful": 45,
    "failed": 2,
    "avg_response_time": 1245,
    "phronetic_used": 18
  },
  "recent_activity": [
    {
      "identity_email": "recruitment@nhtech.link",
      "sender_email": "applicant@example.com",
      "subject": "Frontend Developer Position",
      "model_used": "gpt-4o-mini",
      "success": true,
      "response_time_ms": 1221,
      "created_at": "2025-10-10T19:45:22"
    }
  ]
}

---

🧠 How to Integrate with SendGrid

1. Go to SendGrid → Settings → Inbound Parse

2. Add your domain (e.g., nhtech.link)

3. Point the destination URL to your server’s endpoint:

   https://yourdomain.com/inbound_email
   

4. Enable “POST the raw email” option.

---

🧩 Architecture Summary

• FastAPI handles all webhooks and REST endpoints.
• PostgreSQL stores agent identity configurations and logs.
• OpenAI / Phronetic provides AI-generated email replies.
• SendGrid manages both inbound and outbound email flow.
• CORS enabled for all origins to support browser-based dashboards.

---

🔒 Security Notes

• Restrict CORS in production to trusted domains.
• Rotate API keys regularly.
• Run behind HTTPS (required by SendGrid).
• Add authentication for admin endpoints (/agent_identity_prompts, /stats).

---

🧑‍💻 Contributing

Contributions and extensions are welcome! Ideas include:

• /stats/{identity} endpoint
• Admin UI for managing agents
• Token cost dashboard
• WebSocket live feed for inbox monitoring

---

🏁 License

MIT License © 2025 NightHack Technology Pvt. Ltd.

---

“AgentBox — Because your inbox deserves an intelligent assistant.”

---

Would you like me to add a **“Quick Deploy to Render.com”** section next — with prebuilt environment variables and start command for one-click Render deployment?