Writes a new article and returns it. Needs content: write, and is a write.

The article's text goes in content_markdown, as Markdown: the same rendition GET /articles/{article} returns as content_markdown under ?expand=content, so what you read back is what you send. HTML is not accepted. Commune parses it strictly: text it cannot read answers 400 naming the line, and nothing is written, rather than guessing at a document you did not write and sending it to your list.

What you get is always a draft. status, posted_at and scheduled_for are not properties of the request. A draft is invisible on every reader surface, so nothing this operation does reaches anybody. It goes out through Schedule an article (POST /articles/{article}/schedule) or Send an article to the list (POST /articles/{article}/send), each of which runs the six gates described on the second before its email leaves Commune.

Send no body at all and Commune seeds one. {} creates an empty untitled draft: two blank lines and an editable unsubscribe line. Send a body and it is stored exactly as sent, with nothing appended. The send operations refuse an article whose body carries no unsubscribe mechanism and no postal address, so a body you intend to send should carry {{ unsubscribe_url }} and {{ address }}.

Only a newsletter Commune publishes. A newsletter whose esp is anything but commune has its articles written elsewhere and mirrored into Commune afterwards, so there is nothing here to create. That answers 422 with the code not_commune_newsletter, whose docs_url is https://usecommune.dev/errors/not_commune_newsletter, the page on what the refusal means and how to move a newsletter onto Commune.

Publishes no event. A draft has neither gone out nor been queued, and status is what says so until one of those happens.

The Markdown content_markdown takes

Headings, paragraphs, bold, italic, strikethrough, inline code, links, images, blockquotes, bullet and ordered lists, fenced code blocks with a language, tables and thematic breaks. A line ending in two spaces or a backslash is a line break; a code fence without a language is stored without one rather than guessed at.

Merge tags survive exactly as written. {{ subscriber.first_name }} and {% if %} are personalization rather than Markdown, so nothing inside a Liquid construct is escaped or read as formatting.

Raw HTML is refused rather than passed through or dropped. Write a literal < as \<.

The five components

Five things the editor can hold have no Markdown spelling, so they get an MDX-shaped syntax. The set is closed: any other tag name is a 400.

• <Section> ... </Section> wraps blocks in a styled band. Optional backgroundColor, textColor (hex, with the #), fontFamily (sans, serif, mono), fontSize (a number, in px) and textAlign (left, center, right).
• <EmailOnly> ... </EmailOnly> wraps blocks that belong in the inbox and not on the web. This is where the unsubscribe line and the mailing address go: on the website there is no subscriber, so the link is dead and the address is noise. Commune seeds exactly this into a draft created with no body.
• <Button href="...">Label</Button> is a call to action. href is required; alignment is optional.
• <Socials items={[...]} /> is a row of linked platform icons. items is required and is a JSON array of {"platform": "...", "url": "...", "imageUrl": null}. Optional align, iconColor and iconBgColor.
• <YouTube url="..." /> is a video. The URL has to be one Commune can read a video id out of (youtube.com/watch?v=, youtu.be/, youtube.com/shorts/ or youtube.com/embed/), because the email shows a thumbnail built from that id rather than an iframe, which every major email client strips.

Attributes are written name="value" or name={json}. A component that holds nothing is written self-closing; one that holds content is opened and closed on their own lines.

{
  "title": "What we learned in March",
  "preview_text": "The third one surprised us.",
  "content_markdown": "# What we learned in March\n\nThree things, and the **third** one surprised us.\n\n<EmailOnly>\n[Unsubscribe]({{ unsubscribe_url }}) | {{ address }}\n</EmailOnly>\n"
}

{
  "short_id": "k7Rm2xQp",
  "newsletter": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "authors": [
    {
      "object": "newsletter",
      "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
    }
  ],
  "thread": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  }
}