Inbox

The Inbox feature lets external services, scripts, or automations push articles directly into FeedCraft over HTTP. Each inbox is then exposed as an RSS feed through a Custom Recipe, making it easy to subscribe in any RSS reader.

Overview

A typical workflow looks like this:

1. Create an Inbox in the admin dashboard (gives you a unique inbox ID).
2. Create a System Auth Token (the secret that authorises push requests).
3. Push items from your script, automation, or third-party tool using a standard JSON HTTP POST.
4. Create a Custom Recipe that uses the inbox as its data source.
5. Subscribe to the generated RSS URL in your reader.

Managing Inboxes

Navigate to Worktable > Generate Feed Sources > Push Inbox in the admin dashboard.

Creating an Inbox

1. Click Create Inbox.
2. Fill in the required fields:
   • Inbox ID: A unique, URL-safe identifier (lowercase letters, numbers, hyphens, underscores). Cannot be changed after creation.
   • Title: A human-readable name for this inbox.
   • Max Items: Maximum number of articles to retain. When the limit is exceeded, the items with the oldest creation time are pruned first (default: 100). Set to 0 to impose no limit — note that 0 actually deletes all items immediately, so use a large number instead.
   • Public Access: If enabled, article content can be fetched without authentication. If disabled, a valid System Auth Token must be provided.
3. Click OK to save.

Editing an Inbox

Click Edit Inbox in the actions column to update the Title, Description, Max Items, or Public Access setting. The Inbox ID cannot be modified.

Caution

Reducing Max Items on an existing inbox immediately prunes overflow articles, removing those with the oldest creation timestamps first. Pruned articles cannot be recovered.

Deleting an Inbox

Click Delete in the actions column. This permanently removes the inbox and all articles stored inside it.

Managing System Auth Tokens

Navigate to Settings > System Auth Token to create API tokens that authorise push requests.

1. Click Generate Token.
2. Enter a descriptive label (e.g., “iPhone Shortcut”, “Home Assistant”).
3. Copy the generated token immediately — it is only shown once and cannot be retrieved later.

Tokens can be revoked at any time by clicking Delete. All integrations using the revoked token will stop working immediately.

Pushing Articles

Use the push endpoint to send articles from any HTTP client, script, or automation platform.

Endpoint

POST /api/inbox/{inbox_id}/items

Authentication

Include the System Auth Token in the Authorization header:

Authorization: Bearer YOUR_SYSTEM_AUTH_TOKEN
Content-Type: application/json

Request Body

Send a JSON array of article objects. Only title is required; all other fields are optional.

[
  {
    "id": "optional-custom-unique-id",
    "title": "Article Title",
    "url": "https://example.com/article",
    "content": "<p>Full HTML body of the article.</p>",
    "summary": "A short description shown in feed previews.",
    "author": "Author Name",
    "timestamp": 1716470400
  }
]

Field	Required	Description
title	✅	Article headline.
id	Optional	Custom stable ID. If omitted, a UUID is auto-generated. If the same id is pushed again, the article is updated (upsert).
url	Optional	Canonical link. If omitted, FeedCraft generates a link pointing to the article’s stored content.
content	Optional	Full HTML body.
summary	Optional	Short description. Defaults to the first 200 Unicode characters (runes) of content.
author	Optional	Author name.
timestamp	Optional	Unix timestamp (seconds) for the publication date. Defaults to the current time.

Batch limit: Maximum 100 items per request.

cURL Example

curl -X POST "https://YOUR_SERVER/api/inbox/my-inbox/items" \
  -H "Authorization: Bearer YOUR_SYSTEM_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"title": "Hello World", "content": "<p>First article pushed!</p>"}]'

Response

{
  "total": 1,
  "created": 1,
  "updated": 0
}

Subscribing via RSS

Direct RSS URL (simplest)

Every inbox has a built-in RSS endpoint you can subscribe to immediately — no Custom Recipe required:

GET /inbox/{inbox_id}/rss

Copy this URL and paste it directly into your RSS reader. For a private inbox, append your token as a query parameter:

/inbox/{inbox_id}/rss?token=YOUR_SYSTEM_AUTH_TOKEN

Via Custom Recipe (advanced)

Create a Custom Recipe if you want to apply Craft processing on top of the inbox (e.g., AI translation, summarization, or filtering).

1. Navigate to Worktable > Manage Feed Sources > Recipes and click Create Recipe.
2. Set Source Type to inbox.
3. In the Source Config JSON field, enter:

   { "inbox_source": { "inbox_id": "YOUR_INBOX_ID" } }

4. Set Craft to the desired processing chain (e.g., translate-content, summary).
5. Save the recipe and click Copy Link in the recipe list to get the RSS URL.

Tip

Use the Direct RSS URL for simple subscriptions. Switch to a Custom Recipe only when you need to apply AI processing (translation, summarization, filtering) on the inbox content.

Access Control for Private Inboxes

When an inbox has Public Access disabled, the article content endpoint requires authentication.

Append ?token=YOUR_SYSTEM_AUTH_TOKEN to the article URL:

GET /inbox/{inbox_id}/items/{article_id}/content?token=YOUR_TOKEN

Or use the Authorization: Bearer YOUR_TOKEN header.

Note

The RSS feed itself (served via Custom Recipe) is controlled by the Recipe’s own access settings, not the inbox’s public flag. The private flag only affects the raw article content endpoint at /inbox/{inbox_id}/items/{article_id}/content.

Maintenance (GC)

FeedCraft provides garbage collection utilities accessible from the admin API:

• GET /api/admin/inboxes/gc/stats — Returns the count of total items, orphaned items (belonging to deleted inboxes), and overflow items.
• POST /api/admin/inboxes/gc/cleanup — Deletes all orphaned and overflow items in a single atomic transaction.