Inputs:

• title (string): Title of the post
• subtitle (string): Subtitle of the post
• body (string): Body of the post. Plain text becomes one paragraph per line — Markdown is not interpreted, so ## Heading arrives literally. A JSON string of a Substack document also works and is validated against the same schema set_post_body publishes, so an unrecognised node name is an error rather than a silently mangled post.

Returns: {draft_id, is_published}. Pass draft_id to get_draft to read the draft back.

For anything structured — headings, lists, links, code, images, a paywall — use set_post_body after creating the draft: the schema is published there, so the calling model can read the node vocabulary rather than guess at it.

Exposes the same filtering the Subscribers dashboard offers: 48 columns, 18 operators, free-text search, sorting and pagination.

Inputs:

• filters (array, optional): conditions combined with AND, each {column, operator, value}
• search (string, optional): free text matched against subscriber name and email
• sort_by (string, optional): any filterable column
• sort_direction (asc | desc, optional): defaults to desc
• limit (number, optional): 1–100, defaults to 25
• offset (number, optional): for paging

Which operators a column accepts depends on its type:

The columns cover subscriber identity (name, email, country, state, group membership), subscription (type, start/expiry/cancel dates, revenue, Stripe plan, attribution), email engagement (opens and unique opens over 7d/30d/6mo, links clicked, sections) and site engagement (post views, unique posts seen, comments, shares, days active, activity rating). The full list with types reaches the client in the tool's JSON Schema, so a model does not have to guess names.

Returns: {count, returned, limit, offset, subscribers}. count is the total matching the filters regardless of limit, so a call with limit: 1 is a cheap way to size a segment.

Note: engagement columns can be filtered on here but are not part of the records this tool returns — Substack takes the fields it returns from the publication's saved Display settings and ignores a per-request column list. Use export_subscribers to read their values.

There is no OR and no nesting: anything needing OR has to be issued as separate calls.

The way to actually read the engagement metrics list_subscribers can only filter on: email opens over 7d/30d/6mo, unique emails seen, post views, unique posts seen, comments, shares, links clicked, days active and activity rating.

Inputs:

• filters (array, optional): the same conditions as list_subscribers, combined with AND
• search (string, optional): free text matched against subscriber name and email
• columns (array, optional): which columns to include, defaulting to all of them
• max_wait_seconds (number, optional): 1–600, defaulting to 120

Returns: {count, columns, missing_columns, unmapped_columns, export_id, subscribers}, where each subscriber is keyed by column name.

Substack generates the file asynchronously, so the tool creates a subscriber set, requests the export, polls until it is ready and downloads it. A small export lands in a few seconds. If the wait budget runs out the tool says so and names the export_id rather than blocking.

Two caveats, both verified against the live API:

• tag_ids and group_membership cannot be exported. Substack drops them silently rather than failing, so they are reported in missing_columns — asking for all 48 columns returns 46.
• Values arrive display-formatted, not raw: revenue is "€50.00" here and the number 50 through list_subscribers. Dates are ISO strings.

There is no paging: an export covers the whole matching set.

Inputs:

• status (drafts | published | scheduled): which list to read
• search (string, optional): free text matched against title and content
• limit (number, optional): 1–100, defaults to 25
• offset (number, optional): for paging
• sort_direction (asc | desc, optional): drafts and published posts are newest-first, scheduled posts soonest-first

Returns: {status, total, returned, limit, offset, posts}, each post summarised — use get_draft for the full content of an unpublished one.

Inputs:

• draft_id (number): the id returned by list_posts or create_draft_post

Returns: the draft as Substack stores it, body and audience/email settings included.

The only way to write structured content: headings, lists, links, code blocks, quotes, images, buttons and a paywall. create_draft_post takes plain text; this takes the document Substack actually stores, and its schema is published in tools/list so the calling model can read the node vocabulary instead of guessing.

Inputs:

• draft_id (number): the id returned by list_posts or create_draft_post
• body (object): a Substack ProseMirror document — {type: 'doc', content: [...]}