API referenceAI helpers

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

What each credential can reach on the AI routes
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. 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:

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

Suggest subject lines

POST /ai/subject-lines

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

Body

subjectstring
The current subject, if any.
htmlstring
The HTML body, up to 100,000 characters.
textstring
The plain-text body, up to 100,000 characters.
audiencestring
Who the email is for, up to 2,000 characters.

1 more field (template_id)

template_idstring
One of the team's templates, recorded as what the request was about. The content still comes from this body.

Request

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"
}'

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();

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

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

Draft an email body

POST /ai/draft

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

Body

briefstringRequired
What the email should say, up to 2,000 characters.
tonestring
neutral, friendly or formal.
existing_htmlstring
A draft to rework instead of starting fresh, up to 100,000 characters.

1 more field (template_id)

template_idstring
One of the team's templates, recorded as what the request was about.

Request

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"
}'

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();

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

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

Diagnose an email

POST /emails/{email_id}/diagnose

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

Path parameters

email_idstringRequired
The email's ID.

Request

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"

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();

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

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