# Transactional — Umney Connect API

> For AI agents. Cloudflare-style token: service **Transactional**, permission `transactional:send`.
> **Live** public REST under `/api/v1/transactional/*`. Email delivery requires Business Email entitlement.
> Prefer customer-facing names. Do not expose internal billing catalog IDs.

## Quick facts

| Item | Value |
|---|---|
| Service | Transactional |
| Status | Public Transactional API **live** |
| Permission | `transactional:send` |
| Key | `umk_live_transactional_<8>_<secret>` |
| HTML | https://umneyconnect.com/developers/transactional |
| Markdown | https://umneyconnect.com/developers/transactional.md |
| OpenAPI | https://umneyconnect.com/developers/openapi-transactional.json |
| UI | Dashboard → Email Suites |
| JWT live | GET\|POST /api/growth/transactional/templates; GET /api/growth/transactional/logs; GET /api/growth/transactional/statistics |
| Production API | https://umneyconnect.com/api |

## Create access

1. Enable **Transactional** and **Business Email** in Billing (send needs both).
2. Create API token with `transactional:send` (Dashboard → Developers).
3. Store secret server-side only.

```
CONNECT_API_BASE=https://umneyconnect.com/api
TRANSACTIONAL_API_KEY=umk_live_transactional_…
```

## Public API (token — live)

| Method | Path | Permission | Status |
|---|---|---|---|
| GET\|POST | `/v1/transactional/templates` | transactional:send | **Live** |
| GET\|PATCH\|DELETE | `/v1/transactional/templates/{id}` | transactional:send | **Live** |
| POST | `/v1/transactional/messages` | transactional:send | **Live** |
| GET | `/v1/transactional/logs` | transactional:send | **Live** |

### Template `bodyJson`

```json
{
  "subject": "Order {{orderId}} confirmed",
  "html": "<p>Hi {{name}}</p>",
  "text": "Hi {{name}}"
}
```

`{{var}}` merges from send `variables`.

### Send

```bash
curl -X POST "$CONNECT_API_BASE/v1/transactional/messages" \
  -H "Authorization: Bearer $TRANSACTIONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "uuid",
    "to": ["user@example.com"],
    "variables": { "name": "Ada", "orderId": "123" }
  }'
```

Inline override without template: `to`, `subject`, and `html` or `text`. Email channel only — no SMS/WhatsApp invent.

### Logs

`GET /v1/transactional/logs?limit=50` defaults to `metadata.source=transactional_v1`. Use `?source=all` for the shared activity ledger (also written by Marketing + Business Email).

## Concepts

| Resource | Description |
|---|---|
| Template | Named channel + body_json for system messages |
| Message send | Template or inline content → edge email provider |
| Log | Attempt row (`sent` / `failed`) with metadata |

Transactional Suite owns templates + template-send API. Delivery uses the same platform email providers as Business Email.

## Agent checklist

1. /llms.txt → this file + openapi-transactional.json
2. Enable Transactional + Business Email → create token → store secret
3. Create template with subject/html → POST /messages
4. Do not invent segment crawl, SMS, or dial endpoints
5. Prefer customer-facing service names