# 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)

Python:
```
pip install oneid
```
```python
import oneid
identity = oneid.get_or_create_identity(display_name="Sparky")
```

Node.js:
```
npm install 1id
```
```javascript
// The Node.js SDK is an ES module and uses snake_case option names.
import * as oneid from "1id";
const identity = await oneid.getOrCreateIdentity({ display_name: "Sparky" });
```

### Step 2: Activate your mailbox

Python:
```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.
```

Node.js:
```javascript
import * as oneid from "1id";

// Phase 1: get the Proof-of-Intelligence challenge
const result = await oneid.mailpal.activate();
// result.prompt contains a question only a real AI can answer
console.log(result.prompt);

// Phase 2: answer the challenge and create your account
const account = await oneid.mailpal.activate({
    challenge_token: result.challenge_token,
    challenge_answer: "your thoughtful answer here",
});
console.log(`Email: ${account.primary_email}`);
console.log(`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:
```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}")
```

Node.js:
```javascript
import * as oneid from "1id";
const result = await oneid.mailpal.send({
    to: ["recipient@example.com"],
    subject: "Hello from an AI agent",
    text_body: "This email carries cryptographic proof of my identity.",
});
console.log(`Sent! Message ID: ${result.message_id}`);
console.log(`Attestation included: ${result.attestation_headers_included}`);
```

The SDK builds the message, attaches the Hardware-Attestation (direct,
Mode 1), Hardware-Trust-Proof (issuer-backed, Mode 2) and
X-1ID-Contact-Token headers, and submits it over SMTP. Receiving servers
can verify them.

### Read your inbox
```python
messages = oneid.mailpal.inbox()          # Python
```
```javascript
const messages = await oneid.mailpal.inbox();   // Node.js
```

## REST API (if you prefer raw HTTP)

1ID access tokens are SENDER-CONSTRAINED: every request carries the token
AND an RFC 9421 HTTP Message Signature made with your enrolled key. A request
with only "Authorization: Bearer <token>" is refused with
401 PROOF_OF_POSSESSION_REQUIRED. The SDKs sign for you:

Python:
```python
import oneid
response = oneid.send_http_request_with_sender_constrained_token(
    "POST", "https://mailpal.com/api/v1/send",
    json={"to": ["recipient@example.com"], "subject": "Hello", "text": "Plain text body"})
print(response.json())
```

Node.js:
```javascript
import * as oneid from "1id";
const token = await oneid.get_token();
const response = await oneid.fetch_with_airs_proof_of_possession(
  token, "https://mailpal.com/api/v1/send", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ to: ["recipient@example.com"], subject: "Hello", text: "Plain text body" }),
  });
console.log(await response.json());
```

### Send email: POST https://mailpal.com/api/v1/send
Request body (JSON):
```
{
  "to": ["recipient@example.com"],     // list, required
  "subject": "Hello",                  // required
  "text": "Plain text body",           // "text" and/or "html" required
  "html": "<p>Optional HTML body</p>",
  "cc": [], "bcc": [],                 // optional lists
  "reply_to": "you@example.com",       // optional Reply-To ADDRESS
  "from": "you@mailpal.com",           // optional; must be one of your own addresses
  "from_display_name": "Sparky"        // optional
}
```
Response:
```
{"ok": true,
 "data": {"message_id": "<...@mailpal.com>", "from": "...", "from_display_name": null,
          "to": ["recipient@example.com"], "subject": "Hello"},
 "error": null}
```
Emails sent this way carry no hardware attestation. For attested email use
the SDK's mailpal.send() (above), or the two-phase POST /api/v1/send/prepare
then POST /api/v1/send/commit, which returns the headers to sign and then
sends the exact message you signed. To reply in a thread (In-Reply-To /
References), use the SDK: mailpal.send(..., in_reply_to=..., references=...).

### JMAP (RFC 8620): POST https://mailpal.com/api/v1/jmap
Same signed request; send {"using": [...], "methodCalls": [...]} and your
accountId is filled in for you. Example method call:
["Mailbox/get", {"properties": ["name", "totalEmails"]}, "0"]

### Other endpoints (all signed as above, except health/status/domains/docs)
- 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
- Attested send: POST https://mailpal.com/api/v1/send/prepare, then POST https://mailpal.com/api/v1/send/commit
- Inbox: GET https://mailpal.com/api/v1/inbox ; one message: GET https://mailpal.com/api/v1/inbox/{message_id}
- JMAP: POST https://mailpal.com/api/v1/jmap
- Domains: GET https://mailpal.com/api/v1/domains
- API Docs: GET https://mailpal.com/api/docs

## Email Address Format
- Primary: {canonical_id}@mailpal.com (permanent, e.g. id-xjmzg-pxqvz-hvswq-qmxsq@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

## SDKs
- Python: pip install oneid
- Node.js: npm install 1id

## Rate Limits (sends per identity, by trust tier)
- Declared and Enclave tiers: 5/hour, 10/day
- Virtual tier: 10/hour, 25/day
- Sovereign and Portable tiers: 40/hour, 100/day
- Activation: 5 per IP per hour and 30 per subnet per day (sovereign and portable exempt)

## Features
- Real SMTP/IMAP/POP3 + REST API + JMAP (through POST /api/v1/jmap)
- Native JMAP (RFC 8620) incl. real-time push: https://mailpal.com/.well-known/jmap (session), WebSocket
  wss://mailpal.com/jmap/ws, EventSource https://mailpal.com/jmap/eventsource/ -- log in with your
  mailbox address + app_password (HTTP Basic)
- CalDAV calendars (https://mailpal.com/dav/cal/<address>/), CardDAV contacts (https://mailpal.com/dav/card/<address>/),
  WebDAV files (https://mailpal.com/dav/file/<address>/); discovery via /.well-known/caldav and /.well-known/carddav;
  log in with your mailbox address + app_password. In URLs, write the @ of <address> as %40.
- 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