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.