← All action domains

Copywriting

14 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.

Build the sequence

copywriting.build_series_workflowwriteconfirm

Turn a generated sequence into a real automation: one 'send email' step per email with a genuine wait between them, saved onto an existing workflow's flow graph so it can be edited in the visual builder. DESTRUCTIVE — it replaces that workflow's entire flow, so use an empty or throwaway workflow unless you mean to overwrite. The automation is left PAUSED with a manual start trigger: no contact is enrolled and no email is sent until someone chooses a trigger and turns it on.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
workflow_idstring (uuid)requiredThe workflow whose flow graph will be REPLACED. Create one with automations.create first.
seriesobjectrequiredThe sequence to compile, in the shape copywriting.write_series returns.
series.namestringrequiredName of the sequence.
series.framework_id"aappa" | "acca" | "aicpbsawn" | "aida" | "bab" | "big-domino" | … 39 morerequiredWhich copywriting framework to follow. Call copywriting.list_frameworks for the catalogue, or copywriting.suggest_framework to have one picked from who the audience is.
series.emailsobject[]requiredThe emails, in sending order — normally taken straight from copywriting.write_series.
series.emails[].rolestringrequiredThe email's role in the arc — 'Episode 2 - High Drama'.
series.emails[].subjectstringrequiredSubject line.
series.emails[].preheaderstringoptionalPreview text shown after the subject.
series.emails[].blocksobject[]requiredThe email body, in order.
series.emails[].blocks[].type"heading" | "text" | "button"requiredBlock kind.
series.emails[].blocks[].textstringrequiredThe block's copy.
series.emails[].blocks[].hrefstringoptionalButton destination; buttons only.
series.emails[].delayobjectrequiredGap AFTER THE PREVIOUS email. Ignored for the first, which always sends immediately.
series.emails[].delay.amountintegerrequiredHow long to wait.
series.emails[].delay.unit"minutes" | "hours" | "days"requiredUnit for the wait.
email_identity_idstring (uuid)optionalSending identity for every email. Omit to use the account default.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.build_series_workflow \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "series": {
      "name": "Example",
      "framework_id": "aappa",
      "emails": [
        {
          "role": "example",
          "subject": "Example",
          "blocks": [
            {
              "type": "heading",
              "text": "example"
            }
          ],
          "delay": {
            "amount": 1,
            "unit": "minutes"
          }
        }
      ]
    }
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_build_series_workflow at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete a saved draft

copywriting.delete_draftwriteconfirm

Permanently delete one draft from the AI Writer's Recent list. This cannot be undone. Only the saved copy in the list goes: an automation already built from a sequence, and anything already pasted into a campaign, stay exactly as they are.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe draft to delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.delete_draft \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_delete_draft at https://app.chirply.io/api/mcp, same bearer token, same input.

View brand voice

copywriting.get_brand_voiceread

Read the account's writing rules — audience, what it sells, tone, reading level, whether it speaks as 'I' or 'we', sign-off, banned words, emoji policy and any pasted writing sample. These shape every AI-generated email, subject line and sequence. Read-only.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.get_brand_voice \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool copywriting_get_brand_voice at https://app.chirply.io/api/mcp, same bearer token, same input.

Open a saved draft

copywriting.get_draftread

Fetch one draft from the AI Writer's Recent list in full: what was asked for (intent, audience, call to action, or the pasted email and rewrite instruction), the complete result (the email's subject, preheader and body blocks; every email of a sequence with its waits; or a grade's scores and fixes) and a copy-ready plain-text version. Read-only; generates nothing and costs nothing.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe draft id, from copywriting.list_drafts or a generator's draft_id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.get_draft \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_get_draft at https://app.chirply.io/api/mcp, same bearer token, same input.

Open a framework

copywriting.get_frameworkread

Read one copywriting framework in full — its origin, the psychology it relies on, its step-by-step arc, strategic notes, the mistakes it warns against, the objections it pre-handles, a worked example email, and its campaign breakdown (the email-by-email brief used to generate a sequence). Read-only and free.

Parameters

FieldTypeRequiredDescription
framework_id"aappa" | "acca" | "aicpbsawn" | "aida" | "bab" | "big-domino" | … 39 morerequiredWhich copywriting framework to follow. Call copywriting.list_frameworks for the catalogue, or copywriting.suggest_framework to have one picked from who the audience is.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.get_framework \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "framework_id": "aappa"
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_get_framework at https://app.chirply.io/api/mcp, same bearer token, same input.

Grade an email

copywriting.grade_emailread

Score an existing email against a copywriting framework, step by step: what the draft does at each stage of the arc, the specific fix for each, a subject-line score with three stronger alternatives, and which of the framework's known mistakes the draft is making. The grade is kept in the AI Writer's Recent list (its id comes back as draft_id); it changes nothing else and sends nothing. Runs on its own OpenRouter account and bills it for the tokens used.

Parameters

FieldTypeRequiredDescription
framework_id"aappa" | "acca" | "aicpbsawn" | "aida" | "bab" | "big-domino" | … 39 morerequiredWhich copywriting framework to follow. Call copywriting.list_frameworks for the catalogue, or copywriting.suggest_framework to have one picked from who the audience is.
subjectstringrequiredThe draft's subject line.
bodystringrequiredThe draft's body — plain text or HTML.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.grade_email \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "framework_id": "aappa",
    "subject": "Example",
    "body": "example"
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_grade_email at https://app.chirply.io/api/mcp, same bearer token, same input.

AI Writer recent work

copywriting.list_draftsread

List the AI Writer's Recent list for this account — every email, sequence, grade and rewrite the writer has produced (in the app, over the API, MCP or Copilot), pinned ones first, then newest. Each row has its id, kind, framework, title (subject line or sequence name), a short preview and whether it is pinned. Read-only; generates nothing and costs nothing. Open one in full with copywriting.get_draft.

Also answers to ai writer history, recent ai writing, saved drafts, my generated emails.

Parameters

FieldTypeRequiredDescription
kindsarray of ("email" | "series" | "grade" | "rewrite")optionalOnly these kinds: email, series (a sequence), grade, rewrite. Omit for all.
pinnedbooleanoptionaltrue for pinned drafts only, false for unpinned only. Omit for both.
searchstringoptionalMatch against the draft's title and preview text.
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.list_drafts \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "pinned": true,
    "search": "example"
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_list_drafts at https://app.chirply.io/api/mcp, same bearer token, same input.

Browse frameworks

copywriting.list_frameworksread

List the 45 built-in email copywriting frameworks — AIDA, PAS, Soap Opera Sequence, SPIN Selling and the rest — each with the reader awareness it assumes, the psychological levers it pulls, and how many emails its own arc runs to. Read-only and free; nothing is generated or sent.

Parameters

FieldTypeRequiredDescription
category"marketing" | "direct-response" | "sales" | "professional" | "meta-strategic" | "tactical" | … 2 moreoptionalOnly frameworks in this family.
sequences_onlybooleanoptionalOnly frameworks whose own arc spans more than one email, for building a sequence.
searchstringoptionalMatch against name, overview and when-to-use text.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.list_frameworks \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "marketing",
    "sequences_only": true
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_list_frameworks at https://app.chirply.io/api/mcp, same bearer token, same input.

Pin a draft

copywriting.pin_draftwrite

Pin a draft so it stays at the top of the AI Writer's Recent list, or unpin it (pinned: false). Changes only the list's order; the draft itself, campaigns and automations are untouched and nothing is sent.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe draft to pin or unpin.
pinnedbooleanoptionaltrue to pin (the default), false to unpin. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.pin_draft \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_pin_draft at https://app.chirply.io/api/mcp, same bearer token, same input.

Rewrite an email

copywriting.rewrite_emailread

Rewrite an existing email so it follows a chosen framework, keeping every fact, offer, price and link from the original and changing only the structure and language. Returns a draft for review and keeps it in the AI Writer's Recent list (its id comes back as draft_id): the original is untouched, nothing is saved to a campaign and nothing is sent. Runs on its own OpenRouter account and bills it for the tokens used.

Parameters

FieldTypeRequiredDescription
framework_id"aappa" | "acca" | "aicpbsawn" | "aida" | "bab" | "big-domino" | … 39 morerequiredWhich copywriting framework to follow. Call copywriting.list_frameworks for the catalogue, or copywriting.suggest_framework to have one picked from who the audience is.
subjectstringrequiredThe current subject line.
bodystringrequiredThe current body — plain text or HTML.
instructionstringoptionalAnything extra to apply while rewriting — 'make it half the length', 'drop the discount'.
knowledge_topic_idstring (uuid)optionalNarrow the AI Brain facts used for grounding to one knowledge topic. Omit to use all of the account's knowledge.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.rewrite_email \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "framework_id": "aappa",
    "subject": "Example",
    "body": "example"
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_rewrite_email at https://app.chirply.io/api/mcp, same bearer token, same input.

Save brand voice

copywriting.set_brand_voicewriteadmin only

Replace the account's writing rules. Every field is overwritten with what you pass, so send the whole voice, not just the parts you are changing. This changes how all future AI-generated copy sounds; it does not rewrite anything already written, and sends no email.

Parameters

FieldTypeRequiredDescription
audiencestringrequiredWho this account writes to — 'independent gym owners with 100-400 members'.
productstringrequiredWhat the account sells, in a sentence or two.
tone"friendly" | "direct" | "professional" | "playful" | "authoritative" | "warm" | … 1 morerequiredOverall tone: friendly, direct, professional, playful, authoritative, warm or blunt.
tone_notesstringrequiredAnything the tone presets miss, in the user's own words.
reading_level"simple" | "standard" | "technical"required'simple' for phone-skimmable, 'standard' for everyday business English, 'technical' to assume field jargon.
perspective"i" | "we"required'i' to write as one named person, 'we' to write as the company.
sign_offstringrequiredHow emails end, used verbatim — 'Talk soon, Jon'. Empty for none.
banned_wordsstring[]requiredWords and phrases the AI must never use. Empty list for none.
emoji"never" | "sparingly" | "freely"required'never', 'sparingly' (at most one) or 'freely'.
samplestringrequiredA pasted sample of real writing for the AI to imitate in rhythm and vocabulary. Empty for none.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.set_brand_voice \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "audience": "example",
    "product": "example",
    "tone": "friendly",
    "tone_notes": "example",
    "reading_level": "simple",
    "perspective": "i",
    "sign_off": "example",
    "banned_words": [
      "example"
    ],
    "emoji": "never",
    "sample": "example"
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_set_brand_voice at https://app.chirply.io/api/mcp, same bearer token, same input.

Suggest a framework

copywriting.suggest_frameworkread

Rank the frameworks that fit a particular audience and goal, with the reason for each. Say where the audience stands with the business (cold, engaged, customer, gone quiet) and what the email is for, and this matches that against the reader-awareness stage each framework was built for. Read-only and free — it picks nothing and writes nothing.

Parameters

FieldTypeRequiredDescription
relationship"cold" | "engaged" | "customer" | "lapsed"requiredWhere the audience stands: 'cold' (never engaged), 'engaged' (opens and clicks, hasn't bought), 'customer' (has bought), 'lapsed' (used to engage or buy and stopped).
goal"nurture" | "sell" | "reengage" | "onboard" | "announce" | "follow_up"requiredWhat the email is for: 'nurture', 'sell', 'reengage', 'onboard', 'announce' or 'follow_up'.
sequencebooleanoptionalTrue when you want a multi-email sequence rather than one email.
limitintegeroptionalHow many suggestions to return. Default 6.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.suggest_framework \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "relationship": "cold",
    "goal": "nurture"
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_suggest_framework at https://app.chirply.io/api/mcp, same bearer token, same input.

Write an email

copywriting.write_emailread

Write one complete email — subject line, preheader and body blocks — following a chosen copywriting framework, in the account's brand voice, grounded in the facts stored in its AI Brain. Returns a draft for review and keeps it in the AI Writer's Recent list (its id comes back as draft_id): nothing is saved to a campaign and nothing is sent. Runs on its own OpenRouter account and bills it for the tokens used.

Parameters

FieldTypeRequiredDescription
framework_id"aappa" | "acca" | "aicpbsawn" | "aida" | "bab" | "big-domino" | … 39 morerequiredWhich copywriting framework to follow. Call copywriting.list_frameworks for the catalogue, or copywriting.suggest_framework to have one picked from who the audience is.
intentstringrequiredWhat this email has to achieve, in plain language — 'get lapsed gym members to book a free week back' — not a subject line.
audiencestringoptionalWho is receiving it, e.g. a segment or list name. Shapes vocabulary and assumed knowledge.
call_to_actionstringoptionalWhat clicking the button should do — 'book a call', 'start the free trial'.
knowledge_topic_idstring (uuid)optionalNarrow the AI Brain facts used for grounding to one knowledge topic. Omit to use all of the account's knowledge.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.write_email \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "framework_id": "aappa",
    "intent": "example"
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_write_email at https://app.chirply.io/api/mcp, same bearer token, same input.

Write a sequence

copywriting.write_seriesread

Write a complete multi-email sequence from a framework's own campaign breakdown — each email written to its role in the arc ('Episode 2 - High Drama'), with a sending delay chosen to suit the framework's pacing. Returns drafts for review and keeps the sequence in the AI Writer's Recent list (its id comes back as draft_id): no automation is created, nothing is scheduled and nothing is sent. Pass the result to copywriting.build_series_workflow to turn it into a real automation. Runs on its own OpenRouter account and bills it for the tokens used; a long sequence is a large generation.

Parameters

FieldTypeRequiredDescription
framework_id"aappa" | "acca" | "aicpbsawn" | "aida" | "bab" | "big-domino" | … 39 morerequiredWhich copywriting framework to follow. Call copywriting.list_frameworks for the catalogue, or copywriting.suggest_framework to have one picked from who the audience is.
intentstringrequiredWhat this email has to achieve, in plain language — 'get lapsed gym members to book a free week back' — not a subject line.
audiencestringoptionalWho is receiving it, e.g. a segment or list name. Shapes vocabulary and assumed knowledge.
call_to_actionstringoptionalWhat clicking the button should do — 'book a call', 'start the free trial'.
knowledge_topic_idstring (uuid)optionalNarrow the AI Brain facts used for grounding to one knowledge topic. Omit to use all of the account's knowledge.
email_countintegeroptionalHow many emails to write. Defaults to the framework's own breakdown length, which is what its arc was designed around.

Example

curl -X POST https://app.chirply.io/api/v1/actions/copywriting.write_series \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "framework_id": "aappa",
    "intent": "example"
  }'
Test with your API key

Over MCP the same operation is the tool copywriting_write_series at https://app.chirply.io/api/mcp, same bearer token, same input.

The machine-readable version of this page is GET https://app.chirply.io/api/v1/actions?domain=copywriting — same operations, with full JSON Schemas. Authentication, errors and rate limits are covered in the API documentation home.