Sends

Retrieve a send

One dispatch, by the identifier a send.completed or send.failed event carried, or the one a retry reported back. Needs sending: read.

This is the operation those events point at. An identifier arrives on a webhook and this reads the run behind it, so a consumer does not have to have kept the payload to be able to ask again.

Expanding article inlines an Article, which is content rather than sending, so it also needs content: read on this newsletter. A credential that holds sending: read without it is refused with 403 insufficient_scope, param set to expand, and allowed_values listing what it may expand instead (newsletter). Unexpanded, article is a reference and needs nothing more. Accepted paths are article and newsletter.

get/sends/{send}

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/sends/{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:read)

Query parameters

expandstring

Comma-separated list of relationship paths to inline in the response. Unexpanded relationships are returned as a reference object carrying only id and object. Each operation documents the paths it accepts, and an unknown path answers 400. Nested paths use a dot, for example article.newsletter.

fieldsstring

Comma-separated allow-list of top level properties to return on each object, so a client can trim a response it does not need in full. id and object are always returned. An unknown property name answers 400. Properties omitted by an operation, such as content on any article list, cannot be brought back with fields.

Response

The send.

object'send' required

Always send.

idstring uuid required

Stable identifier for the run. The send_id on send.completed and on send.failed is this value.

started_atstring date-time nullable

When the run began handing recipients to the provider.

completed_atstring date-time nullable

When the run finished handing every recipient over. Null while it is still going, and null for a run that broke before it could finish. The counts below mean nothing until this is set.

recipient_countinteger required

Audience size fixed at the moment the run started. The stable denominator for any rate a consumer computes.

sent_countinteger required

Recipients the provider accepted at dispatch. NOT confirmed deliveries: confirmation arrives later as delivery.delivered, one event per recipient.

failed_countinteger required

Recipients the provider rejected outright at dispatch.

created_atstring date-time required

When the run was recorded, which is the same instant as started_at for every run Commune has made. The collection is ordered by this rather than by started_at, which can be absent.

Example response

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

Changes

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