Articles

Schedule an article

Queues this article to go out at a time you choose.

Only a draft or an already scheduled article can be scheduled, and scheduled_for has to be in the future. Scheduling an already scheduled article moves it, which is how a send time is changed: there is no separate reschedule.

A scheduled article is not published. Its status becomes scheduled and posted_at stays null, so it stays invisible on every reader surface until it goes out. The newsletter's own credentials can read it, which is how you check what is queued.

Every gate Send an article to the list (POST /articles/{article}/send) runs is run here, so a missing footer, an unreachable image, an unverified sending address or an empty body refuses the schedule now rather than failing silently at six in the morning.

The time is honoured to within a few minutes, not to the second. Commune dispatches queued articles in passes, so scheduled_for is the moment from which an article may go out rather than the moment it will.

Publishes article.scheduled.

post/articles/{article}/schedule

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/articles/{article}/schedule
  • 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

scheduled_forstring date-time required

The moment from which the article may go out. Has to be in the future. Commune dispatches queued articles in passes, so this is the earliest it will go rather than the exact moment it does.

acknowledge_broken_imagesboolean

Schedule even though an image in the body will not load. See the same field on the send operation for what this acknowledges and how long it lasts.

Example request

{
  "scheduled_for": "2026-10-01T09:00:00Z"
}

Response

The article, as it now stands: status is scheduled and scheduled_for is the time it will go out from.

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.