# ARC-Relay — Agent-Readable Service Description

> ARC-Relay is a DMARC-compliant email forwarding relay. It adds ARC sealing
> and SRS rewriting so forwarded emails pass SPF, DKIM, and DMARC checks at
> Gmail, Outlook, Yahoo, ProtonMail, and all major providers.

---

## What ARC-Relay Does

ARC-Relay solves the #1 problem with custom-domain email forwarding: **DMARC failures** that cause forwarded emails to land in spam or be silently rejected.

It applies two RFC-standard mechanisms in a single pass:
- **ARC Sealing** ([RFC 8617](https://datatracker.ietf.org/doc/html/rfc8617)) — preserves original authentication across forwarding hops
- **SRS Rewriting** ([RFC 7208](https://datatracker.ietf.org/doc/html/rfc7208)) — fixes SPF alignment by rewriting the envelope sender

Result: **100% DMARC pass-through** at Gmail, Outlook, Yahoo, ProtonMail, and all ARC-aware providers.

---

## API Endpoints

### Public (no auth required)

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/health` | Service health check |
| GET | `/api/tools/dmarc/:domain` | Check a domain's DMARC record |
| GET | `/api/tools/spf/:domain` | Validate a domain's SPF record |

### Authenticated (Bearer token)

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/me` | User profile + stats |
| GET | `/api/domains` | List configured domains |
| POST | `/api/domains` | Add a domain |
| GET | `/api/logs` | Paginated relay logs (JSON) |
| GET | `/api/logs?format=markdown` | Relay logs as markdown table |
| GET | `/api/analytics` | 30-day analytics (JSON) |
| GET | `/api/analytics?format=markdown` | Analytics as markdown report |
| GET | `/api/report/markdown` | Full combined markdown report |
| GET | `/api/export` | GDPR data export (JSON) |

### Content Negotiation

All public pages support `Accept: text/markdown` header or `?format=markdown` query parameter:

- `/` (landing page)
- `/features.html`
- `/pricing.html`
- `/docs.html`
- `/faq.html`
- `/tools/`
- `/privacy.html`
- `/terms.html`

---

## Pricing

| Plan | Price | Domains | Forwards/mo | DKIM Signing |
|---|---|---|---|---|
| Free | $0/mo | 3 | 500 | No |
| Pro | $9/mo | 50 | 10,000 | Yes |
| Business | $29/mo | Unlimited | 100,000 | Yes |
| Enterprise | Custom | Unlimited | Custom | Yes |

---

## Quick Integration

1. Sign up at https://arc-relay.com/signup.html
2. Add your domain in the dashboard
3. Set MX record: `10 mx.arc-relay.com`
4. Add TXT verification record (provided in dashboard)
5. Emails start forwarding with full DMARC compliance

---

## How It Works (Technical)

```
Sender → MX lookup → mx.arc-relay.com (port 2525, STARTTLS)
  → Authenticate message (SPF, DKIM, DMARC)
  → Add ARC-Seal headers (ARC-Authentication-Results, ARC-Message-Signature, ARC-Seal)
  → SRS rewrite envelope sender (SRS0=hash=TT=domain=user@arc-relay.com)
  → Optional: Add DKIM-Signature for user's domain (Pro+)
  → Forward via Postfix (localhost:25) → destination inbox
  → Result: SPF pass, DKIM pass, DMARC pass
```

---

## MCP (Model Context Protocol) Integration

ARC-Relay exposes a full MCP server at `POST /mcp`, allowing AI agents to manage email forwarding directly.

### Configuration

Add to your Claude Desktop `claude_desktop_config.json`, Cursor, or any MCP client:

```json
{
  "mcpServers": {
    "arc-relay": {
      "url": "https://arc-relay.com/mcp",
      "headers": {
        "Authorization": "Bearer <api-key-or-supabase-token>"
      }
    }
  }
}
```

Public tools (DMARC/SPF check) work without the Authorization header.

**Authentication:** Use a persistent API key (prefix `ar_live_...`, created in Settings) or a Supabase JWT token. API keys are recommended for MCP integrations.

**Scopes:** API keys can be restricted to least-privilege scopes (`mcp:read`, `domains:write`, `domains:admin`, `network:read`, `network:operator`, `network:requester`). `tools/list` only shows the tools your credential can actually call, and out-of-scope calls are rejected with the missing scope named. Keys created without scopes have full access.

### Available MCP Tools (42)

**Public (no auth):**
- `check_dmarc` — Check a domain's DMARC, SPF, and MX records
- `check_spf` — Validate SPF record with mechanism analysis
- `check_health` — Service health status
- `check_email_health` — 0-100 email health score with grade and recommendations
- `network_stats` — Public relay network statistics
- `network_leaderboard` — Top relay nodes ranked by reputation

**Domain Management:**
- `list_domains`, `add_domain`, `delete_domain`, `verify_domain`, `dns_health`

**Alias Management:**
- `list_aliases`, `create_alias`, `delete_alias`

**Sender Rules:**
- `list_sender_rules`, `create_sender_rule`, `delete_sender_rule`

**Logs & Analytics:**
- `get_logs`, `get_analytics`, `get_report`

**DKIM (Pro+):**
- `generate_dkim`, `get_dkim_status`, `disable_dkim`

**DNS Monitoring (Pro+):**
- `enable_monitoring`, `disable_monitoring`, `get_monitoring_status`, `list_monitoring_alerts`

**Destructive operations are two-step:** `delete_domain` and `disable_dkim` first return `confirmation_required` with a short-lived `confirm_token` and a plain-language warning; repeat the call with that `confirm_token` to proceed. Budget two tool calls for these.

**Account & Usage:**
- `get_profile`, `get_usage`, `bulk_health_score`

**Relay Network — Node Management:**
- `list_nodes` — List your registered relay nodes
- `get_node` — Get node details and reputation metrics
- `register_node` — Register a new SMTP relay node
- `retire_node` — Retire a relay node

**Relay Network — Staking & Credits:**
- `stake_credits` — Stake credits on a node (100 min to activate)
- `unstake_credits` — Withdraw staked credits
- `get_credits` — Get your credit balance
- `get_credit_history` — View credit transaction history

**Relay Network — Marketplace:**
- `list_jobs` — Browse open routing jobs
- `post_routing_job` — Post a mail routing job (credits held upfront)
- `claim_job` — Claim an open job with your node
- `complete_job` — Report job completion (triggers settlement)

### MCP Resources

Browsable data via `resources/read` — agents can inspect these without calling tools:

| URI | Auth | Description |
|---|---|---|
| `arc-relay://network/stats` | None | Relay network statistics |
| `arc-relay://network/leaderboard` | None | Top nodes by reputation |
| `arc-relay://profile` | Required | Your profile, plan, and stats |
| `arc-relay://domains` | Required | Your configured domains |
| `arc-relay://analytics` | Required | 30-day email analytics |
| `arc-relay://credits` | Required | Credit balance and lifetime stats |
| `arc-relay://nodes` | Required | Your relay nodes with reputation |
| `arc-relay://usage` | Required | API usage this billing period |

---

## OpenAPI Spec

Full REST API schema available at [`/openapi.json`](https://arc-relay.com/openapi.json) (OpenAPI 3.1).

---

## Contact

- Support: support@arc-relay.com
- Enterprise: enterprise@arc-relay.com
- Website: https://arc-relay.com