# Business Email — Umney Connect API

> For AI agents: use this file for Business Email, transactional send, and marketing contact questions.
> Access model matches Cloudflare API tokens: create a least-privilege **Business Email** token so an agent can only use email resources.
> Prefer customer-facing names (Business Email). Do not invent or expose internal billing catalog IDs.

## Quick facts

| Item | Value |
|---|---|
| Service | Business Email |
| Status | Public Business Email API **live** · dashboard Mail API also live |
| HTML docs | https://umneyconnect.com/developers/business-email |
| OpenAPI | https://umneyconnect.com/developers/openapi-business-email.json |
| Token guide | https://umneyconnect.com/developers/api-tokens |
| Dashboard | Dashboard → Business Email |
| Permissions | `email:send`, `email:read` |
| Live token | `umk_live_email_<prefix>_<secret>` |
| Test token | `umk_test_email_<prefix>_<secret>` |
| Production API | https://umneyconnect.com/api |

## Create access

1. Enable **Business Email** in Dashboard → Billing.
2. Ensure email providers are configured (SES default; optional Resend / Mailgun / Brevo).
3. Dashboard → Developers → create an API token → product **Business Email** → choose permissions.
4. Store the secret server-side only.

```
CONNECT_API_BASE=https://umneyconnect.com/api
EMAIL_API_KEY=umk_live_email_…
```

## Public API (token — live)

| Method | Path | Permission | Status |
|---|---|---|---|
| POST | `/v1/email/messages` | email:send | **Live** |
| GET | `/v1/email/messages` | email:read | **Live** |
| GET | `/v1/email/messages/{id}` | email:read | **Live** |
| POST | `/v1/email/contacts` | email:send | **Live** |
| GET | `/v1/email/status` | email:read | **Live** |

### POST /v1/email/messages

```bash
curl -X POST "$CONNECT_API_BASE/v1/email/messages" \
  -H "Authorization: Bearer $EMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["customer@example.com"],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order</p>",
    "text": "Thanks for your order",
    "tags": ["receipt"]
  }'
```

Optional: `cc`, `bcc`, `from`, `replyTo`, `headers`, small `attachments[]` (`filename`, `contentBase64`, `contentType`).

Activity logs use `metadata.source=email_v1` (shared `transactional_logs` table).

### POST /v1/email/contacts

Upserts to configured Resend audience / Mailgun list / Brevo lists. Returns per-provider `{ ok, error? }`.

## Dashboard Mail API (JWT)

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/mail/status` | Provider readiness + entitlement |
| POST | `/api/mail/send` | Admin transactional send |
| POST | `/api/mail/marketing/contact` | Admin marketing contact upsert |

## Related

- **Transactional** suite — template-based sends (`/v1/transactional/*`) also require Business Email for delivery.
- **Marketing** — campaign send uses the same email providers.

## Agent checklist

1. /llms.txt → this file
2. Enable Business Email → create `email:send` / `email:read` token
3. Prefer public `/v1/email/*` for integrations; JWT `/api/mail/*` for dashboard admins
4. Do not invent SMS/WhatsApp or crawl endpoints