Loss-aware draft export

Version 0.6.0 adds read-only Substack draft backups as Markdown.

substack drafts export 12345
substack drafts export 12345 --output backup.md
substack --json drafts export 12345

result = api.export_draft_to_markdown(12345)

Exports preserve supported Markdown semantics. Unsupported nodes remain visible as versioned, URL-safe base64 JSON markers and are also returned in unsupported_nodes.

Existing files require --force. Export performs no server writes.

See the 0.6.0 release notes for the full details.

Added

• Resolve publication_url dynamically against Substack subdomains and custom domains.
• Allow optional timeout configuration for the API client and CLI.
• Detect local image MIME types (JPEG, PNG, GIF, WebP) for uploads instead of defaulting to JPEG.
• Add Dependabot configuration (#74).

Improved

• Raise SubstackRequestException explicitly instead of failing silently when a publication is unavailable.
• Expand secret redaction to cookie-like values in request error messages to prevent credential leaks.
• Ensure bounded retries apply strictly to safe GET and DELETE requests only.
• Bump fastmcp from 3.2.0 to 3.4.7 (#73).
• Bump markdown-it-py from 3.0.0 to 4.2.0 (#72).
• Bump pre-commit from 4.6.1 to 4.6.2 (#71).
• Bump requests from 2.33.0 to 2.34.2 (#70).
• Bump python-dotenv from 1.2.2 to 1.2.3 (#69).

layout: default
title: Release 0.4.0
parent: Releases

Release 0.4.0

This release makes the optional MCP server significantly more useful for inspecting and preparing publications without steering agents toward immediate publishing.

Added

• Seven new MCP tools for read operations and safe publishing: get_status, list_publications, list_drafts, get_draft, schedule_draft, unschedule_draft, and publish_draft_checked.
• Pre-publish validation, interactive confirmation requirements, and no-email defaults for the new publish_draft_checked MCP tool.
• Verified MCP client configuration examples in docs/mcp.md.
• Documentation for Gemini CLI with Vertex AI (docs/gemini-vertex-ai.md).

Improved

• Simplify MCP draft creation by routing through the existing Api.create_draft_from_markdown SDK helper, preserving response format.
• Document the legacy publish_draft MCP tool as the compatibility interface.
• Bump cryptography dependency from 48.0.1 to 50.0.0 (#68).

python-substack 0.3.0 gives new users a focused five-minute path from installation to a safe unpublished Substack draft and publishes the complete documentation on GitHub Pages.

Highlights

• Task-oriented documentation for installation, authentication, CLI, Python, Markdown, MCP, safety, and troubleshooting.
• A five-minute Markdown-to-unpublished-draft walkthrough with before and after images.
• Tested examples for draft creation, scheduling, publication selection, JSON automation, and authentication verification.
• Existing documentation paths remain available.

No runtime interface changed in this release.

Read the documentation

python-substack 0.2.0

Version 0.2.0 makes python-substack easier to adopt safely and establishes the
compatibility and release-security foundation for the path to 1.0.

Highlights

• Start with a three-command Markdown-to-draft workflow.
• See the draft-only safety guarantee before any publishing instructions.
• Use focused guides for authentication, Markdown, legacy commands, the
  low-level Python API, YAML, and MCP.
• Rely on a documented compatibility commitment for existing Python, CLI,
  JSON, environment, console-script, and MCP interfaces.
• Follow dedicated contributing and security-reporting policies.
• Install artifacts published through short-lived PyPI Trusted Publishing
  credentials.
• Develop with current pre-commit, Black, and isort hooks.

No runtime interface changed in this release.

Quick start

pip install -U python-substack
substack status
substack drafts create post.md

The final command creates an unpublished draft. Review it in Substack before
running a separate publish command.

Compatibility

Existing Python APIs, five console scripts, unified CLI commands and flags,
defaults, JSON keys, environment variables, and MCP tools remain available.
Legacy standalone commands remain supported throughout the 1.x series.

Announcement copy

python-substack 0.2.0 is now organized around one safe workflow: write in
Markdown, create an unpublished Substack draft, review it, and publish only
when ready. The release adds focused authentication, CLI, Python, YAML, MCP,
compatibility, contributing, and security documentation while moving PyPI
publishing to short-lived trusted credentials. Install it with
pip install -U python-substack.

python-substack 0.1.27

Version 0.1.27 turns a Markdown file into a rich Substack draft through the
main CLI and strengthens package validation around that workflow.

Highlights

• Create an unpublished draft with substack drafts create post.md.
• Set title, subtitle, audience, comment permissions, SEO metadata, slug,
  section, and repeatable tags from the unified CLI.
• Render inline and block LaTeX, superscript, subscript, pull quotes, and
  callouts from Markdown.
• Handle both known subscriber-count response formats.
• Restore draft scheduling and unscheduling against Substack's current endpoint.
• Retry rate-limited reads and deletes with bounded backoff while avoiding unsafe POST retries.
• Keep live Substack tests opt-in while validating offline tests on Python 3.10
  through 3.14 and clean wheel installations on Python 3.10 and 3.14.

Existing Python APIs, MCP tools, environment variables, standalone console
commands, defaults, and CLI output contracts remain available.

Quick examples

substack drafts create post.md
substack --json drafts create post.md --tag python --tag substack
substack drafts publish 12345 --no-send

Creation never publishes, schedules, sends, or deletes a draft. Publishing
remains a separate command with the existing confirmation safeguards. If tag
assignment fails after Substack creates the draft, the draft may remain in the
publication and is not deleted automatically.

Observable Markdown changes

Text matching the new $...$, $$...$$, ^...^, ~...~, :::pullquote,
or :::callout syntax now produces corresponding Substack document nodes.
Ordinary currency amounts remain text, and ~~...~~ remains strikethrough.

Announcement copy

python-substack 0.1.27 can now turn a Markdown file directly into a rich,
unpublished Substack draft with substack drafts create post.md. The release
adds LaTeX, superscript, subscript, pull quotes, and callouts, while strengthening
clean-install and release validation. Install it with
pip install -U python-substack.

python-substack 0.1.26

Version 0.1.26 adds a unified command-line interface for day-to-day Substack operations.

Highlights

• Check authentication, publication selection, and subscriber count with substack status.
• List publications and inspect drafts without writing Python code.
• Schedule, unschedule, publish, and delete drafts with explicit safety controls.
• Use --json for stable machine-readable output in scripts and automation.
• Override the selected publication per command with --publication-url.
• Run on Python 3.10 through 3.14 with pull-request CI and validated release artifacts.

Existing Python APIs, MCP tools, environment variables, and console commands remain available.

Quick examples

substack status
substack drafts list
substack --json drafts get 12345
substack drafts schedule 12345 --at 2026-08-01T09:00:00+03:00
substack drafts publish 12345 --no-send

Announcement copy

python-substack 0.1.26 is now a practical Substack operations CLI as well as a Python SDK. The new substack command can inspect publications and drafts, manage schedules, publish without sending email, and safely delete drafts. It also provides stable JSON output for automation. Install it with pip install -U python-substack.

0.1.25

Added

• Markdown-first draft helper: Api.create_draft_from_markdown(...).
• CLI commands: substack-auth-check, substack-publish-markdown, substack-publish-yaml, substack-mcp.
• Optional MCP extra: python-substack[mcp].
• .env.example, CHANGELOG.md, funding metadata, and GitHub issue templates.

Fixed

• Include substack_mcp in packaged distributions.
• Fix examples/publish_post.py --publish so the flag publishes.
• Correct MCP documentation to use substack_mcp.mcp_server.

Improved

• Reworked README around Markdown, cookie auth, CLI usage, and MCP setup.
• Added PyPI classifiers, project links, and focused tests.

Release 0.1.24\n\n- Render from_markdown via markdown-it-py.\n- Add broader Markdown round-trip coverage for footnotes, lists, images, captions, and formatting.\n- Keep live Substack API tests opt-in and offline-safe by default.

What's Changed

• Bump python-multipart from 0.0.26 to 0.0.27 by @dependabot[bot] in #51
• Bump urllib3 from 2.6.3 to 2.7.0 by @dependabot[bot] in #52
• Bump idna from 3.11 to 3.15 by @dependabot[bot] in #53
• Bump authlib from 1.6.11 to 1.6.12 by @dependabot[bot] in #54
• Bump starlette from 1.0.0 to 1.0.1 by @dependabot[bot] in #55
• Bump starlette from 1.0.1 to 1.3.1 by @dependabot[bot] in #57
• Bump cryptography from 46.0.7 to 48.0.1 by @dependabot[bot] in #58
• Bump python-multipart from 0.0.27 to 0.0.31 by @dependabot[bot] in #59
• Bump pyjwt from 2.12.1 to 2.13.0 by @dependabot[bot] in #60
• Bump pydantic-settings from 2.13.1 to 2.14.2 by @dependabot[bot] in #62
• Add Markdown footnote support to from_markdown by @MattFisher in #56

New Contributors

• @MattFisher made their first contribution in #56

Full Changelog: v0.1.22...v0.1.23