# AI

Subject lines, a first draft, and an explanation of what happened to an email — the dashboard's three AI helpers, over the API.

## Who can call it

| Credential | All three routes |
| --- | --- |
| `full_access` | 200 |
| `sending_access` | `401 restricted_api_key` |
| OAuth token with `ai:use` | 200 |
| OAuth token without `ai:use` | `403 invalid_permission` |

What is sent to the model and what is kept is described in the [AI assist guide](https://www.rasket.com/docs/ai). A recipient's address is never part of it.

## Refusals, in order

A request that passes authentication is checked in this order, so the first to fail is the one you see:

1. AI assist is not configured for the account: `503 service_unavailable`, "AI assist is not available on this account." Nothing is recorded and no credit is spent; there is nothing to turn on at your end.
2. AI assist is off for the team: `403 invalid_permission`, "AI assist is off for this team. A team admin can turn it on in Settings." Turn it on with `PATCH /team` and `ai_assist_enabled: true`.
3. The month's credits are spent: `422 validation_error`, "AI credits for this month are used up." Every answer carries `credits_remaining`, so you can stop before this.
4. More than 10 AI requests in a minute, per team: `429 rate_limit_exceeded`.

An accepted request spends one credit. A request that fails on our side costs nothing, and a diagnosis read back for an email that has not changed costs nothing either. Nor does a diagnosis of an email that failed on our mail servers' side: it comes back with `cause: "provider_failure"` and the recorded reason.

## Endpoints

### `POST /ai/subject-lines`

Subject lines for an email you describe. Nothing is saved.

#### Body

| Field | Type | Description |
| --- | --- | --- |
| `subject` | string | The current subject, if any. |
| `html` | string | The HTML body, up to 100,000 characters. |
| `text` | string | The plain-text body, up to 100,000 characters. |
| `audience` | string | Who the email is for, up to 2,000 characters. |

#### Body, less common

| Field | Type | Description |
| --- | --- | --- |
| `template_id` | string | One of the team's templates, recorded as what the request was about. The content still comes from this body. |

Suggest subject lines:

```sh
curl -X POST "https://api.rasket.com/ai/subject-lines" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Our November update",
  "text": "Three new features and a price freeze.",
  "audience": "Customers on the Pro plan"
}'
```

```ts
const response = await fetch("https://api.rasket.com/ai/subject-lines", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    subject: "Our November update",
    text: "Three new features and a price freeze.",
    audience: "Customers on the Pro plan"
  }),
});

const data = await response.json();
```

```python
import os

import requests

response = requests.post(
    "https://api.rasket.com/ai/subject-lines",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
    json={
    "subject": "Our November update",
    "text": "Three new features and a price freeze.",
    "audience": "Customers on the Pro plan"
  },
)

print(response.json())
```

#### Response `200`

```json
{
  "object": "ai_subject_suggestions",
  "suggestions": ["Three new features, and your price stays put", "November: what's new on your Pro plan"],
  "credits_remaining": 87,
  "credits": {
    "limit": 100,
    "used": 13,
    "remaining": 87
  }
}
```

- Refused in this order: AI assist not configured for the account is `503 service_unavailable` and costs nothing, AI assist off for the team is `403 invalid_permission`, the month's credits spent is `422 validation_error`, and more than 10 AI requests a minute is `429 rate_limit_exceeded`.
- An accepted request spends one credit.

### `POST /ai/draft`

An HTML and plain-text body from a brief, or a rework of a draft.

#### Body

| Field | Type | Description |
| --- | --- | --- |
| `brief` (required) | string | What the email should say, up to 2,000 characters. |
| `tone` | string | `neutral`, `friendly` or `formal`. |
| `existing_html` | string | A draft to rework instead of starting fresh, up to 100,000 characters. |

#### Body, less common

| Field | Type | Description |
| --- | --- | --- |
| `template_id` | string | One of the team's templates, recorded as what the request was about. |

Draft an email body:

```sh
curl -X POST "https://api.rasket.com/ai/draft" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "brief": "Welcome a new customer and point them at the quickstart.",
  "tone": "friendly"
}'
```

```ts
const response = await fetch("https://api.rasket.com/ai/draft", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    brief: "Welcome a new customer and point them at the quickstart.",
    tone: "friendly"
  }),
});

const data = await response.json();
```

```python
import os

import requests

response = requests.post(
    "https://api.rasket.com/ai/draft",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
    json={
    "brief": "Welcome a new customer and point them at the quickstart.",
    "tone": "friendly"
  },
)

print(response.json())
```

#### Response `200`

```json
{
  "object": "ai_draft",
  "html": "<p>Welcome aboard! …</p>",
  "text": "Welcome aboard! …",
  "credits_remaining": 86,
  "credits": {
    "limit": 100,
    "used": 14,
    "remaining": 86
  }
}
```

- Refused in this order: AI assist not configured for the account is `503 service_unavailable` and costs nothing, AI assist off for the team is `403 invalid_permission`, the month's credits spent is `422 validation_error`, and more than 10 AI requests a minute is `429 rate_limit_exceeded`.
- There is no subject in the answer: ask for subject lines separately. Nothing is saved or sent.

### `POST /emails/{email_id}/diagnose`

What happened to one email, its likely causes, and what to do next.

#### Path parameters

| Field | Type | Description |
| --- | --- | --- |
| `email_id` (required) | string | The email's ID. |

Diagnose an email:

```sh
curl -X POST "https://api.rasket.com/emails/4ef9a417-02e9-4d39-ad75-9611e0fcc33c/diagnose" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"
```

```ts
const response = await fetch("https://api.rasket.com/emails/4ef9a417-02e9-4d39-ad75-9611e0fcc33c/diagnose", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const data = await response.json();
```

```python
import os

import requests

response = requests.post(
    "https://api.rasket.com/emails/4ef9a417-02e9-4d39-ad75-9611e0fcc33c/diagnose",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

print(response.json())
```

#### Response `200`

```json
{
  "object": "ai_diagnosis",
  "summary": "Email 4ef9a417-02e9-4d39-ad75-9611e0fcc33c bounced permanently at one recipient domain.",
  "likely_causes": ["The mailbox does not exist at the receiving domain."],
  "next_steps": ["Remove the address, or confirm it with the recipient."],
  "cause": null,
  "created_at": "2026-09-12T10:00:00.000Z",
  "stored": false,
  "credits_remaining": 85,
  "credits": {
    "limit": 100,
    "used": 15,
    "remaining": 85
  }
}
```

- Refused in this order: AI assist not configured for the account is `503 service_unavailable` and costs nothing, AI assist off for the team is `403 invalid_permission`, the month's credits spent is `422 validation_error`, and more than 10 AI requests a minute is `429 rate_limit_exceeded`.
- The model sees recipient domains, statuses and the event timeline — never a recipient's address or the body.
- A diagnosis already made for the same state of the email comes back with `stored: true` and costs nothing.
- An email that failed on our mail servers' side comes back with `cause: "provider_failure"`: the recorded reason and what to do, with no credit spent.