# Postal Email Infrastructure & AI Integration Scope

## Overview
Vibn requires a scalable, multi-tenant email infrastructure that allows both the core platform and user-generated AI agents to send emails. To support unlimited custom domains without incurring high per-domain or per-email costs, we will self-host **Postal**, an open-source mail delivery platform, on Coolify.

This document outlines the end-to-end implementation plan, covering infrastructure, backend integration, database modifications, and the AI MCP tool.

---

## Phase 1: Infrastructure (Self-Hosted Postal)
*Status: Pending*

Postal requires its own dedicated environment with MariaDB and RabbitMQ. We will deploy this via Coolify's Docker Compose feature.

### 1. Server & DNS Prerequisites
- **Clean IP:** Ensure the Coolify host (or dedicated VPS) IP is not on any DNSBL (Blacklists).
- **Subdomain:** Dedicate a subdomain (e.g., `postal.vibn.com` or `mail.vibn.com`).
- **Reverse DNS (rDNS/PTR):** Configure the hosting provider to map the server's IP back to the Postal subdomain.

### 2. Coolify Deployment
- Create a new **Docker Compose** application in Coolify.
- Use the official Postal docker-compose configuration, which includes:
  - `postal` (The Ruby-based core app)
  - `mariadb` (Relational database for routing/config)
  - `rabbitmq` (Message queue for email spooling)
- Configure environment variables within Coolify (signing keys, DNS hostnames).
- Expose ports: `80/443` (Web UI/API) and `25` (SMTP inbound/outbound).

### 3. Deliverability Foundations
- Generate and configure the global **SPF**, **DKIM**, and **DMARC** records for the Vibn root domain.
- Set up a master "Organization" and "Vibn System" Mail Server inside the Postal UI to generate the first API key.

---

## Phase 2: Backend Integration & Database
*Status: Pending*

We need to securely store Postal credentials and allow individual Vibn projects to configure their own sender identities.

### 1. Database Schema Update (`lib/db-postgres.ts`)
Add an `email_config` JSONB column to the `projects` table to handle multi-tenancy.
```typescript
// Proposed structure for email_config
{
  provider: "postal",
  postalServerKey: "api_key_for_this_specific_project",
  verifiedDomains: ["userapp.com"],
  defaultFrom: "hello@userapp.com"
}
```

### 2. Environment Variables (`.env.local` & Coolify)
Add global fallback variables for Vibn system emails:
- `VIBN_POSTAL_API_URL` (e.g., `https://postal.vibn.com/api/v1`)
- `VIBN_POSTAL_API_KEY`

### 3. Email Utility Client (`lib/email/postal.ts`)
Create a robust TypeScript wrapper for the Postal REST API.
- **Methods:** `sendEmail()`, `createServer()`, `addDomain()`.
- **Logic:** Must support passing a custom API key (for project-specific routing) or falling back to the global key.

---

## Phase 3: AI Agent Integration (MCP Tool)
*Status: Pending*

Expose the ability to send emails to the AI via the Model Context Protocol (MCP).

### 1. Register `send_email` Tool (`vibn-agent-runner/src/tools/vibn-tools.ts`)
Define the JSON Schema for the tool:
- `to`: Array of email addresses.
- `subject`: String.
- `body`: Markdown or Plain Text string.
- *(Optional)* `from`: Override sender address (must match a verified domain).

### 2. Handle MCP Execution (`vibn-frontend/app/api/mcp/route.ts`)
When the AI invokes `send_email`:
1. Extract the `projectId` from the authenticated MCP session.
2. Query the database for the project's `email_config`.
3. Validate that the requested `from` address is authorized for this project.
4. Call the `lib/email/postal.ts` utility.
5. Return the Postal Message ID to the AI so it can confirm delivery in the chat.

---

## Phase 4: User Interface (Optional but Recommended)
*Status: Pending*

To achieve true multi-tenancy, users need a way to connect their custom domains to Postal via the Vibn UI.

### 1. Project Settings -> Email Tab
- A UI where users can click "Add Domain".
- Vibn calls the Postal API to register the domain and retrieve the required DNS records (DKIM, SPF).
- Display these DNS records to the user.
- Add a "Verify DNS" button that queries Postal to confirm the records are active.

---

## Next Steps

To begin, we should tackle **Phase 1: Infrastructure**. 

I can write the exact `docker-compose.yml` you need to paste into Coolify right now. Do you have a specific subdomain in mind for Postal (e.g., `postal.yourdomain.com`)?