Event delivery

Retrieve one delivery attempt

One attempt from the delivery log, by its id. Needs sending: read. The same shape a page of them carries, and what POST /delivery-attempts/{attempt}/replay acts on.

An attempt belonging to another newsletter answers 404, the same as one that does not exist.

The delivery log is kept per newsletter and an attempt is not a Commune object, so there is nothing in the path to work out which newsletter to look in: name it with ?newsletter=. Leave it out if your credential reaches exactly one newsletter.

The body your endpoint answered with is not returned, since a refusing server routinely echoes the request back inside it, credentials included. What came back is response_status, or failure when nothing answered at all; the full body is in the delivery portal.

get/delivery-attempts/{attempt}

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/delivery-attempts/{attempt}
  • 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

newsletterstring

Which newsletter this request is for, by id or by handle.

Most operations never need this. A credential reaches a list of newsletters, and an operation that acts on one of them normally works out which from the object in its path: an article, a thread, a subscriber and a key each belong to a newsletter, so naming one is naming the other. This parameter is for the operations whose subject is not a Commune object, where there is nothing to work it out from.

Leave it out if your credential reaches exactly one newsletter, which is the usual case: it is that one. If your credential reaches several and you leave it out, the answer is 400 naming this parameter, because picking one for you would be picking wrong most of the time.

GET /newsletters lists the newsletters your credential reaches, and is where the value for this comes from.

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 delivery attempt.

object'delivery_attempt' required

Always delivery_attempt.

idstring required

The delivery service's identifier for this attempt. Opaque, and not a UUID: it is minted on the other side of the handover.

destination_typestring

What kind of target it was, as the delivery service named it at the time. Free text for the same reason Destination.type is: the vocabulary belongs to the delivery service and grows there.

event_idstring required

The event that was being delivered, by the id on its envelope. The same string the consumer receives in the Commune-Event-Id header, which makes it the one identifier both sides share and the thing worth logging on yours.

event_typestring nullable required

The topic, matching the keys of the webhooks block of this document. Null only if the delivery service no longer holds the event this attempt belonged to.

status'succeeded' | 'failed' required

How one attempt ended. succeeded is a 2xx from the destination. failed is anything else, including no answer at all, and is not final: the delivery service retries on its own.

response_statusinteger nullable required

The HTTP status the destination answered with. Null when it did not answer at all, in which case failure says why.

failurestring nullable required

Why there was no answer, when there was none: timeout is the common one. Null whenever response_status is set, and the two are never both set or both null. Free text, so treat an unrecognised value as a reason this client does not know how to describe.

attemptinteger required

1 on the first delivery of this event to this destination, and one higher on each retry of it. The number the Commune-Delivery-Attempt header would carry if it were sent.

manualboolean required

Whether somebody asked for this attempt rather than the delivery service making it on its own. True for one made by POST /delivery-attempts/{attempt}/replay or by the retry button in the portal, and false for a first delivery or an automatic retry.

created_atstring date-time required

When the attempt was made.

Example response

{
  "newsletter": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "destination": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "destination_type": "webhook",
  "event_type": "article.published",
  "response_status": 200,
  "failure": "timeout"
}

Changes

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