AI

The AI endpoints generate email copy and resolve @mention references to your own broadcasts, templates, and automations. Generation uses the org's configured AI provider, falling back to the server default (DeepSeek, then Gemini, then Anthropic).

All endpoints require Authorization: Bearer <api_key>. Generation endpoints require full_access scope; mention search accepts read_only and above.

---

Generate subject

POST /v1/ai/generate-subject

Requires full_access scope. Returns up to count subject-line suggestions (default 3), each under 70 characters.

Request body

Field	Type	Required	Description
prompt	string	Yes	What the email is about, the campaign goal, or seed instructions. 1-2000 characters.
context	string	No	Free-form context: existing draft body, brand voice notes, audience description. Max 8000 characters.
tone	string	No	Tone hint, e.g. friendly, urgent, professional. Max 40 characters.
language	string	No	Target language as an ISO-639 name or code, e.g. en, French, pt-BR. Defaults to English.
count	integer	No	Number of alternatives to return (1-6). Default 3.

@slug tokens in prompt or context are resolved to the matching broadcast, template, or automation before generation. See Search mentions.

Example request

{
  "prompt": "Announce the new analytics dashboard to Pro users",
  "tone": "friendly",
  "language": "en",
  "count": 3
}

Response

{
  "suggestions": [
    "Your new analytics dashboard is live",
    "See your numbers like never before",
    "Analytics just got a whole lot clearer"
  ],
  "model": "deepseek-chat"
}

If the provider returns no usable lines, the request fails with 502 ai_empty_response.

---

Generate preview

POST /v1/ai/generate-preview

Requires full_access scope. Returns up to count inbox preview-text (preheader) suggestions (default 3), ideally 40-90 characters. Provide at least one of subject, prompt, or context, otherwise the request returns 400 missing_input.

Request body

Field	Type	Required	Description
subject	string	No*	Subject line the preview should complement. Max 300 characters.
prompt	string	No*	Goal of the email. Max 2000 characters.
context	string	No*	Free-form context. Max 8000 characters.
language	string	No	Target language. Defaults to English.
count	integer	No	Number of alternatives to return (1-6). Default 3.

Example request

{
  "subject": "Your new analytics dashboard is live",
  "prompt": "Encourage Pro users to open the email and try the dashboard"
}

Response

{
  "suggestions": [
    "Log in and see your metrics at a glance",
    "Everything you shipped this month, in one view",
    "Your fastest path to better reports"
  ],
  "model": "deepseek-chat"
}

---

Generate alt-text

POST /v1/ai/generate-alt-text

Requires full_access scope. Returns a single line of alt-text under 125 characters. Provide either imageUrl or imageDescription, otherwise the request returns 400 missing_input.

Request body

Field	Type	Required	Description
imageUrl	string	No*	URL of the image. Max 2048 characters.
imageDescription	string	No*	Short description of what the image shows. Max 2000 characters.
context	string	No	Surrounding email context. Max 8000 characters.
language	string	No	Target language. Defaults to English.

Example request

{
  "imageUrl": "https://cdn.acme.com/hero-dashboard.png",
  "imageDescription": "A product dashboard with a revenue chart and weekly metrics"
}

Response

{
  "altText": "Product dashboard showing a rising revenue chart and weekly metrics",
  "model": "deepseek-chat"
}

---

Search mentions

GET /v1/ai/mention-search

Requires read_only scope. Returns up to limit items per type, ordered by recency. Use the returned slug as the @mention token in a generation prompt.

Query parameters

Parameter	Type	Default	Description
q	string		Case-insensitive search term. Max 200 characters.
types	string	all three	Comma-separated subset of broadcast, template, automation.
limit	string	10	Max results per type (1-25).

Response

{
  "data": [
    {
      "id": "tpl_abc123",
      "type": "template",
      "name": "Onboarding Welcome",
      "slug": "onboarding-welcome",
      "preview": "Welcome to Acme"
    }
  ]
}

Field	Type	Description
id	string	Resource ID.
type	string	broadcast, template, or automation.
name	string	Display name.
slug	string	Kebab-case @mention token, e.g. onboarding-welcome.
preview	string	Optional preview: the subject for broadcasts, template subject, or body excerpt.