# AI in Couryo

> Review before sending (free), writing emails and templates, subject variations, sequences, per-send personalization with {{#ai}} and company research by domain, with AI credits.

Source: https://couryo.com/en/docs/ai

Couryo has AI features to write, review and personalize emails, through the API (`/v1/ai/...`), the dashboard and [MCP](https://couryo.com/en/docs/mcp.md). Two rules apply to all of them:

- **AI never stops an email from going out.** Without credits, on an error or past the time budget, the email goes with the default content and the timeline records why.
- **Research is about companies only.** We never build a profile of a person (see [Company research](#company-research)).

## Credits

Each feature uses AI credits. The review before sending is free.

| Feature | Route | Credits |
|---|---|---|
| Review before sending | `POST /v1/ai/review` | free, up to 200 per account per day |
| Write an email or template | `POST /v1/ai/write` | 10 |
| 5 subject variations | `POST /v1/ai/subjects` | 3 |
| Generate a sequence | `POST /v1/ai/sequence` | 30 |
| Personalize on every send | `personalize` on `POST /v1/emails` | 1 per recipient |
| Company research | `POST /v1/ai/research` | 60 |

**Credits included every month:** Free 100, Pro 2,000, Scale 10,000 and Enterprise 10,000 (or the contract value). They renew every cycle and **do not roll over**: what is left expires when the new cycle starts. On yearly plans, the credit cycle is monthly.

**Packs** (one-time payment): 5,000 credits for US$ 9, 25,000 for US$ 39 and 100,000 for US$ 129 (in Brazil: R$ 49, R$ 199 and R$ 690, with Pix or card). They are valid for 12 months and add up. Monthly credits are used before purchased ones.

**When they run out**, you choose under **Billing > AI credits**: stop (default) or buy 5,000 automatically with the saved card. If the automatic purchase fails, Couryo stops and emails you. We also warn you by email and with a dashboard banner when the cycle reaches 80% and 100%.

Without credits, paid routes answer `402` with the code [`ai_credits_exhausted`](https://couryo.com/en/docs/errors.md#ai_credits_exhausted). If the AI fails, the answer is `503` [`ai_unavailable`](https://couryo.com/en/docs/errors.md#ai_unavailable) and **nothing is charged**.

```bash
curl https://api.couryo.com/v1/ai/credits \
  -H "Authorization: Bearer ck_live_..."
```

The answer has the balance (`balance`), the monthly and purchased credits, the next expirations and this cycle's usage by feature. Scope: `read`.

## Review before sending

`POST /v1/ai/review` (scope `send`) combines fixed rules with a quick AI reading. Send `subject`, `html` and/or `text`, and `stream`:

```bash
curl https://api.couryo.com/v1/ai/review \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Your order arrived", "html": "<p>Hi!</p>", "stream": "marketing" }'
```

The answer has `score` (0 to 100), `summary` and `findings`, each with `code`, `severity` (`error`, `warning`, `info`), `message` and `source` (`rules` or `ai`). What it checks:

- spam risk: words filters watch for, subject or text in capitals, too many exclamation marks, image-only emails;
- links: shorteners, empty or malformed links and links without HTTPS;
- accessibility: images without alternative text and a missing text part;
- unsubscribe: marketing email without a visible unsubscribe link;
- tone and clarity, by the AI.

It is free up to 200 reviews per account per day; after that, `429 rate_limited` until the next day. The [pre-send check](https://couryo.com/en/docs/sending.md#pre-send-check) `POST /v1/emails/check` has no limit.

## Write an email or template

`POST /v1/ai/write` (10 credits) takes `brief` (what the email needs to say), `kind` (`email` or `template`), `language` (`pt-BR` or `en`) and an optional `tone`. It returns `subject`, `html` (simple, responsive, inline styles), `text` and `variables`, the suggested `{{...}}` variables. With `kind: "template"`, personal data becomes variables, ready to save as a [template](https://couryo.com/en/docs/templates.md).

```json
{ "brief": "welcome email for a finance SaaS, with the next step to set up the account", "kind": "template", "language": "en", "tone": "friendly" }
```

`POST /v1/ai/subjects` (3 credits) returns 5 subjects for an A/B test from `brief`, `subject`, `html` or `text`.

## Generate a sequence

`POST /v1/ai/sequence` (30 credits) takes `goal`, `steps` (1 to 7) and `language`, and returns the steps in the same format used to create sequences:

```json
{
  "steps": [
    { "wait": { "amount": 0, "unit": "minutes" }, "subject": "...", "html": "...", "text": "..." },
    { "wait": { "amount": 2, "unit": "days" }, "subject": "...", "html": "...", "text": "..." }
  ]
}
```

`wait` is the delay before each step (`minutes`, `hours` or `days`).

## Personalization

Mark the passages that may change with `{{#ai}}default text{{/ai}}` and send `personalize` on `POST /v1/emails` (or on each batch item):

```json
{
  "from": "Shop <orders@example.com>",
  "to": "ana@example.com",
  "subject": "{{#ai}}Your order arrived{{/ai}}",
  "html": "<p>{{#ai}}Hi! Your order arrived.{{/ai}}</p><p>The Shop team</p>",
  "variables": { "name": "Ana", "city": "Austin", "last_order": "running shoes" },
  "personalize": { "instructions": "mention the name, the city and the last order", "fields": ["name", "city", "last_order"] }
}
```

At send time, the AI rewrites **only** the marked passages, using `variables` (with `fields`, only those keys reach the AI). It costs 1 credit per recipient and has a 4-second budget.

- **Without credits, on an error, past 4 seconds or with an answer that fails the check** (format, a new link, active HTML), the email goes out with the default text, without the markers, and the timeline gets an `ai_fallback` event with the reason (`no_credits`, `timeout`, `error`, `invalid_output`). Nothing is charged when the AI is not applied.
- **Test keys** (`ck_test_`): personalization runs without charging, with a daily limit.
- **Without `personalize`**, the `{{#ai}}` markers are removed and the default text goes as is.
- With `personalize` and no marked passage, the API answers `400 invalid_field` with `param` = `personalize`.

The AI uses only the data you send with the email. It does not look anything up about the person.

## Company research

`POST /v1/ai/research` (60 credits) takes a **company domain** (`example.com`; a website address also works) and returns a public summary: what the company does, industry, approximate size, products and brand tone, with the pages used in `sources`. Use it to personalize B2B emails.

**Why we do not research people:** building a profile of an individual from data scraped from the web would mean processing personal data without a legal basis or transparency, which Brazil's data protection law (LGPD) does not allow, and it would expose you and Couryo. So the route accepts domains only: email addresses, names of people and mailbox provider domains (like gmail.com) are refused with `400 invalid_field` (`param` = `domain`), at no cost. To talk to each person, use [personalization](#personalization) with the data you already have.

## In the dashboard and MCP

The same features are in the dashboard (template editor, sequences and **Billing > AI credits**) and in [MCP](https://couryo.com/en/docs/mcp.md) through the `ai_write`, `ai_review` and `ai_credits` tools, with the key's scopes.