AI in Couryo

Couryo has AI features to write, review and personalize emails, through the API (/v1/ai/...), the dashboard and MCP. 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).

Credits#

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

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. If the AI fails, the answer is 503 ai_unavailable and nothing is charged.

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:

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 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.

{ "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:

{
  "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):

{
  "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 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 through the ai_write, ai_review and ai_credits tools, with the key's scopes.