# Marketing — Umney Connect API

> For AI agents: Marketing campaigns, templates, and `marketing:send` tokens.
> Prefer customer-facing names (Marketing). Do not expose internal billing catalog IDs.
> Email send requires explicit `audience_json.emails[]` (no segment crawl) and **Business Email** entitlement.

## Quick facts

| Item | Value |
|---|---|
| Service | Marketing |
| Status | Public Marketing API **live** · dashboard Growth CRUD live |
| HTML docs | https://umneyconnect.com/developers/marketing |
| OpenAPI | https://umneyconnect.com/developers/openapi-marketing.json |
| Token guide | https://umneyconnect.com/developers/api-tokens |
| Dashboard | Dashboard → Email Suites → Marketing |
| Permissions | `marketing:send` |
| Live token | `umk_live_marketing_<prefix>_<secret>` |
| Test token | `umk_test_marketing_<prefix>_<secret>` |
| Production API | https://umneyconnect.com/api |

## Create access

1. Enable **Marketing** in Billing. For email send also enable **Business Email**.
2. Dashboard → Developers → create token → product **Marketing** → `marketing:send`.
3. Store secret server-side only.

```
CONNECT_API_BASE=https://umneyconnect.com/api
MARKETING_API_KEY=umk_live_marketing_…
```

## Public Marketing API (token — live)

| Method | Path | Permission | Status |
|---|---|---|---|
| GET | `/v1/marketing/campaigns` | marketing:send | **Live** |
| POST | `/v1/marketing/campaigns` | marketing:send | **Live** |
| POST | `/v1/marketing/campaigns/{id}/send` | marketing:send | **Live** (email) |
| GET | `/v1/marketing/templates` | marketing:send | **Live** |
| POST | `/v1/marketing/templates` | marketing:send | **Live** |

### Create campaign

```json
{
  "name": "Spring launch",
  "channel": "email",
  "status": "draft",
  "audienceJson": { "emails": ["lead@example.com"] },
  "contentJson": { "subject": "Hello", "html": "<p>Welcome</p>" }
}
```

### Send campaign

```bash
curl -X POST "https://umneyconnect.com/api/v1/marketing/campaigns/$ID/send" \
  -H "Authorization: Bearer $MARKETING_API_KEY"
```

Rules:

- `channel` must be `email` (SMS/WhatsApp/push not supported on send yet).
- Recipients from `audience_json.emails` (max 50). Segment names are **not** resolved.
- `content_json.subject` required; body via `html`, `text`, or `body`.
- Also requires Business Email entitlement.
- Logs each recipient to transactional activity (`source: marketing_v1`).
- Synchronous; returns `{ sent, failed, results[] }`.

## Dashboard Growth API (JWT — live)

| Method | Path |
|---|---|
| GET\|POST\|PATCH\|DELETE | `/api/growth/marketing/campaigns` |
| GET\|POST | `/api/growth/marketing/templates` |
| GET | `/api/growth/marketing/statistics` |
| GET | `/api/growth/entitlements` |

## Contact sync

Provider list upsert: Business Email `POST /api/mail/marketing/contact` — see `/developers/business-email.md`.

## Errors

- **403** — Marketing / Business Email (on send) / wrong token / missing `marketing:send`
- **400** — missing emails, subject, body; non-email channel
- **503** — all recipient sends failed
- Send: 30/min IP; `/api/v1/*` keys: 600/min

## Agent checklist

1. `/llms.txt` → this file
2. Enable Marketing (+ Business Email for send) → create token
3. Create campaign with `audienceJson.emails` → `POST …/send`
4. Do not invent segment crawl or SMS send
5. Do not expose internal billing catalog IDs