ActivityPub/Primer/Inbox

The inbox property of an Actor object is used for a number of use cases:

• It is the POST endpoint for the federation protocol (server-to-server)
• It is used for fetching the received activities for the client-to-server API

It is required by the ActivityPub standard, and is often used as the main way to distinguish ActivityPub actors from other ActivityPub objects.

The text of the ActivityPub spec defines inbox as:

A reference to an [ActivityStreams] OrderedCollection comprised of all the messages received by the actor; see 5.2 Inbox.

The inbox collection is an ActivityPub object in its own right, and needs to conform to the requirements of the ActivityPub definition for objects -- namely, it should have a dereferenceable identifier, such as an HTTPS URL, and a type, OrderedCollection.

Examples

The value of the inbox property of an ActivityPub actor can be an URL:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Person",
  "id": "https://example.com/person/12345678",
  "name": "James Riley",
  "inbox": "https://example.com/collection/87654321",
  "outbox": "https://example.com/collection/76543218"
}

The value of the inbox property can also be a JSON object, including the id as well as other properties of the inbox collection:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Person",
  "id": "https://example.com/person/12345678",
  "name": "James Riley",
  "inbox": {
     "id": "https://example.com/collection/87654321",
     "type": "OrderedCollection",
     "name": "James Riley's inbox",
     "totalItems": 738
  },
  "outbox": "https://example.com/collection/76543218"
}

The JSON object format has the benefit of sharing important metadata about the collection, such as the totalItems property that counts the number of members of the collection, without requiring an extra HTTP request.

Guidelines for publishers

• Use the URL form for the inbox property. Unfortunately, not all consumers recognize the object form of the inbox property; some require an URL only.
• The inbox collection should be a real ActivityPub object; consumers should be able to GET the id for the inbox, and get its metadata and contents.
• Inboxes for even moderately productive actors on the social web can get very full very fast; it is a good idea to use pagination for the inbox collection.

Guidelines for consumers

• Support both the URL form and the object form of the property. If your implementation is only using the inbox id as an endpoint to POST to, make sure to extract the id property from the object.