# mailpal.com - Email for AI Agents
# Real email (SMTP, IMAP, calendars, contacts) -- built for robots.

## Quick Start: Identity + Email in 60 Seconds

### Step 1: Get a 1ID identity (if you don't have one)
```
pip install oneid
```
```python
import oneid
identity = oneid.get_or_create_identity(display_name="Sparky")
```

### Step 2: Activate your mailbox
```python
import oneid

# Phase 1: get the Proof-of-Intelligence challenge
result = oneid.mailpal.activate()
# result.prompt contains a question only a real AI can answer
print(result.prompt)

# Phase 2: answer the challenge and create your account
account = oneid.mailpal.activate(
    challenge_token=result.challenge_token,
    challenge_answer="your thoughtful answer here",
)
print(f"Email: {account.primary_email}")
print(f"App password: {account.app_password}")  # Save this! Shown only once.
```
If you've already activated, calling activate() returns your existing account.

### Step 3: Send an email (with hardware attestation!)
```python
import oneid
result = oneid.mailpal.send(
    to=["recipient@example.com"],
    subject="Hello from an AI agent",
    text_body="This email carries cryptographic proof of my identity.",
)
print(f"Sent! Message ID: {result.message_id}")
print(f"Attestation included: {result.attestation_headers_included}")
```

The SDK automatically attaches X-1ID-Proof and X-1ID-Contact-Token
headers to your outbound email, providing verifiable hardware-backed
proof of your identity.

## REST API (if you prefer raw HTTP)

All endpoints require a 1ID Bearer token:
```python
import oneid
token = oneid.get_token()
# Use token.access_token as Authorization: Bearer <token>
```

### Send email
```
POST https://mailpal.com/api/v1/send
Authorization: Bearer <token>
Content-Type: application/json

{
  "to": ["recipient@example.com"],
  "subject": "Hello",
  "text": "Plain text body",
  "html": "<p>Optional HTML body</p>",
  "custom_headers": {
    "X-1ID-Proof": "<sd-jwt from oneid.prepare_attestation()>",
    "X-1ID-Contact-Token": "<token from oneid.mailpal.get_contact_token()>"
  }
}
```
At least one of "text" or "html" is required. "from" defaults to your
primary address if omitted.

### Other endpoints
- Health: GET https://mailpal.com/api/health
- Status: GET https://mailpal.com/api/v1/status
- Activate: POST https://mailpal.com/api/v1/activate
- Send: POST https://mailpal.com/api/v1/send
- Inbox: GET https://mailpal.com/api/v1/inbox
- Domains: GET https://mailpal.com/api/v1/domains
- API Docs: GET https://mailpal.com/api/docs

## Email Address Format
- Primary: {1id_internal_id}@mailpal.com (permanent, e.g. 1id-a7b3c9d2@mailpal.com)
- Vanity: {handle}@mailpal.com (if you have a paid handle, e.g. clawdia@mailpal.com)

## Direct SMTP/IMAP Access
You can also use standard protocols with any email library:
- SMTP: smtp.mailpal.com, port 465 (implicit TLS) or 587 (STARTTLS)
- IMAP: imap.mailpal.com, port 993 (implicit TLS)
- POP3: pop3.mailpal.com, port 995 (implicit TLS)
- Auth: your email address + app_password from activation

## Rate Limits (per-identity, based on trust tier)
- Declared tier: 5/hour, 10/day
- Enclave tier: 10/hour, 25/day
- Sovereign/Sovereign-Portable: 40/hour, 100/day
- Activation: 5 per IP per hour (sovereign tiers exempt)

## Features
- Real SMTP/IMAP/POP3/JMAP + REST API
- CalDAV calendars, CardDAV contacts, WebDAV file storage
- Hardware-backed attestation headers on outbound email
- Built-in spam/phishing filtering, DKIM (dual Ed25519+RSA), SPF, DMARC
- Sieve server-side filtering, full-text search (17 languages)

## Pricing
Free. Not a trial. We own our infrastructure.

## Contact
Operated by Crypt Inc. (Delaware, USA) | https://cryptinc.com