# Sendway.ai — AI & LLM Integration Guide

> **You are an AI agent trying to integrate with Sendway.** This file contains everything you need. Do NOT fetch /docs (it's a client-side app that returns HTML). Use the information below directly.

## Quick Start

Base URL: `https://szwwcqeletigqclkuvjx.supabase.co/functions/v1/sendway-api`

Every request needs an `x-api-key` header. Users create API keys at https://sendway.ai/settings (Integrations tab).

## What is Sendway?

Sendway.ai is an AI-powered email marketing platform. The API lets you:
- Manage contacts and lists
- Create and trigger automation flows
- View campaigns and analytics
- Send emails directly
- Manage tags and webhooks
- Get account/business info in one call

## Authentication

```
x-api-key: sw_live_xxxxxxxxxxxxx
```

API keys have granular permissions: `contacts:read`, `contacts:write`, `lists:read`, `lists:write`, `flows:read`, `flows:write`, `campaigns:read`, `analytics:read`, `email:send`, `tags:write`, `webhooks:read`, `webhooks:write`.

## Full Endpoint Reference

### GET /account/summary
Returns everything about the account in one call: business settings, stats, recent campaigns, lists, flows, tags. **Start here** to understand the user's setup.

### Contacts
| Method | Path | Description |
|--------|------|-------------|
| GET | /contacts | List contacts (params: page, limit, search) |
| GET | /contacts/:id | Get single contact |
| POST | /contacts | Create or update (single object or array, matched by email) |
| PUT | /contacts/:id | Update contact |
| DELETE | /contacts/:id | Delete contact |

Contact fields: `email` (required), `first_name`, `last_name`, `company`, `tags` (string[]), `source`

### Lists
| Method | Path | Description |
|--------|------|-------------|
| GET | /lists | All lists with member counts |
| GET | /lists/:id | List details |
| POST | /lists | Create (body: name, description) |
| PUT | /lists/:id | Update |
| DELETE | /lists/:id | Delete |
| GET | /lists/:id/members | List members (params: page, limit) |
| POST | /lists/:id/members | Add contacts (body: contact_ids[]) — triggers flows |
| DELETE | /lists/:id/members?contact_id=ID | Remove member |

### Campaigns
| Method | Path | Description |
|--------|------|-------------|
| GET | /campaigns | List (params: status, page, limit) |
| GET | /campaigns/:id | Full campaign with email content |
| GET | /campaigns/:id/analytics | Delivery stats, open/click rates |

### Automation Flows
| Method | Path | Description |
|--------|------|-------------|
| GET | /flows | List all |
| GET | /flows/:id | Details + enrollment stats |
| POST | /flows | Create flow |
| PUT | /flows/:id | Update flow |
| DELETE | /flows/:id | Delete flow |
| POST | /flows/:id/activate | Activate |
| POST | /flows/:id/pause | Pause |
| POST | /flows/:id/trigger | Enroll contact (body: contact_id or email) |

Flow node types: `trigger`, `email`, `delay`, `condition`, `goal`
Trigger types: `contact_added`, `list_joined`, `tag_added`, `manual`

### Tags
| Method | Path | Description |
|--------|------|-------------|
| GET | /tags | All unique tags |
| POST | /tags/add | Add tags (body: tags[], contact_ids[] or emails[] or filter:"all") |
| POST | /tags/remove | Remove tags (same format) |

### Webhooks
| Method | Path | Description |
|--------|------|-------------|
| GET | /webhooks | List webhooks |
| POST | /webhooks | Register (body: url, events[]) — returns signing secret |
| PUT | /webhooks/:id | Update |
| DELETE | /webhooks/:id | Delete |

Events: `contact.created`, `contact.updated`, `contact.deleted`, `email.sent`, `email.delivered`, `email.opened`, `email.clicked`, `email.bounced`, `email.complained`, `flow.enrolled`, `flow.completed`, `list.member_added`

### Direct Email
| Method | Path | Description |
|--------|------|-------------|
| POST | /email | Send (body: to, subject, html, from_name, from_email) |

## Complete Examples

### 1. Get account overview
```bash
curl -H "x-api-key: sw_live_..." \
  "https://szwwcqeletigqclkuvjx.supabase.co/functions/v1/sendway-api/account/summary"
```

### 2. Add a contact
```bash
curl -X POST \
  -H "x-api-key: sw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"jan@example.com","first_name":"Jan","tags":["new-client"]}' \
  "https://szwwcqeletigqclkuvjx.supabase.co/functions/v1/sendway-api/contacts"
```

### 3. Add contact to list (triggers automation)
```bash
curl -X POST \
  -H "x-api-key: sw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"contact_ids":["CONTACT_UUID"]}' \
  "https://szwwcqeletigqclkuvjx.supabase.co/functions/v1/sendway-api/lists/LIST_UUID/members"
```

### 4. Trigger a flow for a contact
```bash
curl -X POST \
  -H "x-api-key: sw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"jan@example.com"}' \
  "https://szwwcqeletigqclkuvjx.supabase.co/functions/v1/sendway-api/flows/FLOW_UUID/trigger"
```

### 5. Send a direct email
```bash
curl -X POST \
  -H "x-api-key: sw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to":"jan@example.com","subject":"Hello!","html":"<h1>Hi Jan</h1><p>Welcome aboard.</p>"}' \
  "https://szwwcqeletigqclkuvjx.supabase.co/functions/v1/sendway-api/email"
```

### 6. Batch add contacts
```bash
curl -X POST \
  -H "x-api-key: sw_live_..." \
  -H "Content-Type: application/json" \
  -d '[{"email":"a@example.com","first_name":"A"},{"email":"b@example.com","first_name":"B"}]' \
  "https://szwwcqeletigqclkuvjx.supabase.co/functions/v1/sendway-api/contacts"
```

### 7. Get campaign analytics
```bash
curl -H "x-api-key: sw_live_..." \
  "https://szwwcqeletigqclkuvjx.supabase.co/functions/v1/sendway-api/campaigns/CAMPAIGN_UUID/analytics"
```

Response: `{ total_recipients, sent, delivered, opened, clicked, bounced, complained, rates: { delivery_rate, open_rate, click_rate, bounce_rate, complaint_rate } }`

## Error Handling

All errors return JSON: `{ "error": "message" }`

| Status | Meaning |
|--------|---------|
| 401 | Missing or invalid API key |
| 403 | API key lacks required permission |
| 404 | Resource not found |
| 400 | Invalid request body |
| 500 | Server error |

## Machine-Readable Files

- `/llms.txt` — Compact API reference (this file's shorter version)
- `/.well-known/ai-plugin.json` — OpenAI plugin manifest
- `/robots.txt` — Points to llms.txt

## Important Notes for AI Agents

1. **Do NOT fetch /docs** — it's a React SPA and returns an HTML shell
2. **Use /llms.txt or /llms-full.txt** for API documentation
3. **Start with GET /account/summary** to understand the user's account
4. **POST /contacts upserts by email** — it creates or updates, safe to call multiple times
5. **Adding to a list can trigger flows** — this is the main automation mechanism