Articles

Send a test copy of an article

Sends this article to addresses you name, or to yourself when you name none, so somebody can look at it before the list does. Needs sending: write.

Leave out to (or the whole body) and the copy goes to the person the credential belongs to. Their address is not echoed back: the answer says sent_to_owner: true and recipients is empty, because an email address is revealed only by GET /me.

Nobody on the list receives anything. No subscriber is touched, no delivery is recorded, the article's status does not move and no event is published. Run it as often as you like on the same draft: it changes nothing about the article, so a repeat is a second look rather than a second send.

The article is rendered the way a real send renders it, with three differences. Personalization placeholders are filled with example data rather than left as raw text. The unsubscribe link points at a page that explains itself rather than at a live token, so a forwarded test cannot unsubscribe a real person. And the subject is prefixed, so a test is never mistaken for the article.

Three of the six send gates apply here. There has to be an article, a verified sending address, and something in the body. The footer required on commercial email, the article's status and the image reachability check do not refuse a test, so a test is where you go to see that the footer has gone. Send an article to the list (POST /articles/{article}/send) refuses on all six.

Test sends count towards the same daily sending allowance real sends do.

post/articles/{article}/test-send

Request

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

tostring[]

The addresses to send the test to. Leave it out to send it to yourself. A repeated address is sent to once. Five at most, because this is a look before you send rather than a way to reach a group.

Example request

{
  "to": [
    "editor@example.com",
    "proofreader@example.com"
  ]
}

Response

What was attempted and what the sending provider accepted. sent plus failed is always the number of addresses the copy went to, and an address named twice is only sent once.

object'test_send' required

Always test_send.

recipientsstring[] required

Where the test went, deduplicated and in the order given. These are the addresses sent in the request; Commune adds none and reveals none, so this is empty when the copy went to the credential's owner.

sent_to_ownerboolean required

True when the request named no addresses and the copy went to the person the credential belongs to, whose address is not echoed.

sentinteger required

How many of them the sending provider accepted.

failedinteger required

How many it refused. sent plus failed is always the number of recipients, or one when sent_to_owner is true. A test where every address failed answers 502 rather than this shape.

Example response

{
  "article": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  }
}

Changes

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