# Vexm — Comprehensive Platform Documentation & Technical Specifications (llms-full.txt)
> Website: https://vexm.com | Contact: support@vexm.com | Category: Inbound Email SaaS

## 1. Executive Summary
Vexm is an enterprise-grade multi-tenant inbound email management platform. It allows businesses, founders, agencies, and developers to receive, parse, organize, and inspect incoming emails addressed to custom domains without needing to configure individual mailboxes or manage AWS infrastructure.

---

## 2. Platform Architecture

```
[Sender MTA (Gmail/Outlook)]
             │
             ▼ (SMTP Port 25 / TLS)
[Amazon SES Regional Endpoint (us-east-1)]
             │
             ▼ (SES Receipt Rule)
[Encrypted S3 Bucket (Raw RFC822 EML)]
             │
             ▼ (SNS Webhook / Queue)
[Vexm Ingestion Worker (PHP 8.3 / Laravel 12)]
             │
      ┌──────┴─────────────────────────────────┐
      ▼                                        ▼
[MIME Parser & HTML Sanitizer]     [PostgreSQL 16 Multi-Tenant Index]
      │                                        │
      ▼                                        ▼
[Tenant Private S3 Object Store]   [Real-Time Next.js Web Inbox]
```

### Ingestion Lifecycle:
1. **SMTP Delivery**: Sender connects to `inbound-smtp.us-east-1.amazonaws.com`.
2. **Receipt Rule Routing**: Amazon SES matches the recipient domain against active Vexm rule sets and writes the raw RFC822 stream to S3.
3. **Asynchronous Ingestion**: Laravel queue workers fetch the raw EML stream.
4. **MIME Parsing**:
   - Headers: Extracts `From`, `To`, `Cc`, `Bcc`, `Subject`, `Message-ID`, `Date`, `SPF`, `DKIM`, `DMARC`.
   - Multipart bodies: Separates `text/plain` and `text/html`.
   - Attachments: Decodes Base64/Quoted-Printable payloads, generates cryptographic hashes, and isolates files in tenant-scoped S3 storage (`tenants/{tenant_id}/attachments/{hash}`).
5. **Sanitization**: All HTML content is cleansed of script tags, active iframes, tracking pixels, and malicious redirects before rendering in sandboxed `iframe` components.
6. **Indexing**: The metadata is indexed into PostgreSQL with strict tenant ID isolation.

---

## 3. DNS Configuration Guide

To activate catch-all email receiving on any custom domain:

### Record 1: Domain Ownership Verification (TXT)
- **Record Type**: TXT
- **Host / Name**: `_vexm-challenge` (or root `@`)
- **TTL**: 300 seconds (or Auto)
- **Value**: A 64-character SHA-256 cryptographic challenge string generated upon domain registration in the Vexm dashboard.

### Record 2: Inbound Mail Routing (MX)
- **Record Type**: MX
- **Host / Name**: `@` (or root domain)
- **Priority**: `10`
- **Value**: `inbound-smtp.us-east-1.amazonaws.com`

---

## 4. API v1 Endpoints Reference

Base URL: `https://vexm.com/api/v1` (or local `http://localhost:8000/api/v1`)
Authentication: Bearer Token (Laravel Sanctum)

### Authentication
- `POST /auth/register`: Create a new user account. Returns `{ token, user }`.
- `POST /auth/login`: Authenticate existing user. Returns `{ token, user }`.
- `GET /auth/me`: Fetch authenticated profile, subscription plan, and quota consumption.
- `POST /auth/logout`: Revoke API token.

### Custom Domains
- `GET /domains`: List all connected domains, verification statuses, and email counts.
- `POST /domains`: Register custom domain. Payload: `{ domain_name: "example.com" }`.
- `GET /domains/{id}/dns`: Get current DNS verification state and required TXT/MX records.
- `POST /domains/{id}/verify`: Trigger active DNS propagation check for TXT ownership and MX routing records.

### Inbound Inbox & Messages
- `GET /inbox`: Query emails with filters:
  - `folder`: `inbox`, `starred`, `spam`, `archive`, `trash`.
  - `domain_id`: Filter messages by specific custom domain.
  - `search`: Keyword search across subject, sender, and recipient.
  - `has_attachments`: Boolean filter for files.
- `GET /inbox/{id}`: Retrieve message details, sanitized HTML, plain text, and attachment metadata.
- `PATCH /inbox/{id}/star`: Toggle starred flag.
- `PATCH /inbox/{id}/folder`: Move message to specified folder.
- `GET /inbox/{id}/attachments/{attachment_id}/download`: Generate time-limited signed S3 download URL.

### Testing & Simulation
- `POST /inbound/simulate`: Send an instant simulated catch-all test email to verify domain routing without external SMTP clients. Payload: `{ domain_id, recipient, subject, text_body }`.

---

## 5. Security & Multi-Tenancy Guarantee
- **AWS Key Isolation**: Customers never manage or upload AWS IAM keys. All AWS operations are managed behind the scenes with strict least-privilege policies.
- **Tenant Isolation**: PostgreSQL queries are scoped at the model level via `tenant_id`. Insecure direct object reference (IDOR) attacks are rejected with HTTP 403 Forbidden.
- **Data Retention & Purging**: Deleting an email permanently deletes both the PostgreSQL record and the associated raw EML and attachment S3 objects.
- **Zero AI Training**: Customer emails and attachments are never shared with third parties or used to train artificial intelligence models.

---

## 6. Frequently Asked Questions (FAQ)

### Can I send outbound emails with Vexm?
Vexm is strictly focused on inbound email hosting, catch-all reception, and email management. Outbound SMTP sending is intentionally out of scope to protect domain reputation and prevent spam abuse.

### What happens if I already have Google Workspace or Microsoft 365 on my domain?
Changing your domain's MX record to Vexm will route future incoming emails to Vexm instead of your existing provider. Vexm's DNS verification wizard will detect existing MX records and display a warning prior to activation.

### How much does Vexm cost?
Plans start at $3/month (Starter tier: 1 domain, 3,000 emails/mo) up to $39/month (Scale tier: 20 domains, 100,000 emails/mo). All plans include a 7-day free trial.