Articles

Send an article to the list

Sends this article to the newsletter's subscribers. Cannot be undone.

It answers before the article has gone out. The article is queued for immediate dispatch and the answer is 202 with the article as it now stands: status is scheduled and scheduled_for is the moment it was queued. Commune begins sending within a few minutes.

Watch send.completed for the outcome and the counts, or send.failed if the dispatch broke. article.published fires when the article goes live on the web. All three carry the credential that asked for the send and the idempotency key it was made under, so a consumer can tie them back to this call.

Six gates. Four are simple: there has to be an article, a verified sending address, something in the body, and a status that can be sent from. An article that is already sending or sent answers 422. The other two are worth knowing about before you call this:

  • missing_footer (422) when the body no longer carries an unsubscribe link or a mailing address. Both are seeded into a draft as ordinary content and can be edited away, and commercial email is required to carry them. The error names which half is gone.
  • broken_images (422) when an image definitively will not load, naming the URLs and why each one failed. An inbox fetches images when the reader opens the article, so a rotted image is broken for everybody and cannot be repaired after the send. Only a definite answer refuses: a merely slow host is reported and never blocks. Set acknowledge_broken_images to send anyway. That acknowledgement covers the body as it currently reads and any edit clears it.

An article addressed to a tag goes only to the subscribers holding it. An article with no subscribers to send to is still published: it goes live on the web and reports zero recipients.

Failed deliveries are Commune's to follow up. A recipient the sending provider turns away for a moment is retried automatically during the send. One that still fails is followed up by Commune's team rather than re-sent blindly, because some of those may already have been delivered and a second copy is worse than a late one.

Publishes article.scheduled when the article is queued, then article.published and send.completed or send.failed when the dispatch runs.

post/articles/{article}/send

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/articles/{article}/send
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://usecommune.com/api/oauth/authorize, token URL https://usecommune.com/api/oauth/token, scopes: sending:write)

Request body

acknowledge_broken_imagesboolean

Send even though an image in the body will not load for a reader.

Without this, an image Commune could definitively not fetch refuses the send. With it, the send proceeds and the acknowledgement is recorded against the article as it currently reads, so the dispatch that happens a few minutes later honours the same decision. Any edit to the body clears it, which keeps it scoped to the images that were actually looked at.

It does not suppress anything else. An unreadable image is still reported on the article, and the footer gate is not escapable at all.

Response

The article is queued. status is scheduled and scheduled_for is the moment it was queued; sending begins within a few minutes.

object'article' required

Always article.

idstring uuid required

Stable identifier.

short_idstring required

Eight character base62 identifier, unique across Commune. Safe in a URL and accepted anywhere {article} is.

slugstring required

URL segment under the newsletter, unique within it but not across Commune. The permalink is /n/{handle}/a/{slug}. Falls back to the short_id for an untitled article.

titlestring nullable

Subject line of the article. Null for an untitled draft.

preview_textstring nullable

The short line email clients show after the subject, and what Commune uses as the excerpt on a card.

image_urlstring uri nullable

Cover image. When the creator set none, Commune stamps the first image in the body at send time, so this is usually populated for a sent article.

external_urlstring uri nullable

The article's canonical URL on the newsletter's own provider, for an imported article. Null for one written in Commune.

status'draft' | 'scheduled' | 'sending' | 'sent' | 'failed' | 'archived' required

Where an article is in its life. A credential holding only read permissions ever sees sent and nothing else. An imported article is always sent, since Commune sees it after the provider delivered it.

is_importedboolean required

true when the article came in from the newsletter's provider, false when it was written and sent in Commune.

posted_atstring date-time nullable

When the article went out. An article dated in the future is not returned by any read operation until that moment passes, so this is never ahead of now in a response.

scheduled_forstring date-time nullable

When a queued article may go out. Set while status is scheduled and null otherwise.

This is not posted_at and the difference matters: a queued article has no publication date yet, which is why it stays invisible on every reader surface until it really goes out. Commune dispatches in passes, so this is the moment from which the article may go rather than the moment it will.

created_atstring date-time required

When the row was created in Commune.

updated_atstring date-time

When the article was last edited.

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.