v0.10.0

Added

• Export a stable remote revision fingerprint in Markdown backup metadata via python-substack-revision:v1 markers.
• Conflict-aware draft updates: compare submitted expected revision with current remote draft before any write, preventing silent overwrites of remote changes.
• Return actionable mismatch details (body changes, title, subtitle, audience, permissions, section, slug) during dry-run updates (--dry-run --yes).
• Fail closed by default on conflicted updates or missing revision metadata (unprotected updates).
• Add explicit override via --allow-conflict / --force (requiring --yes) in CLI and allow_conflict=True / force=True in SDK.
• Export revision dictionary metadata in Api.export_draft_to_markdown and CLI --json drafts export.
• Introduce DraftConflictError exception inheriting from both ValueError and SubstackException.

v0.9.1

Added

• Export \python-substack-image:v2\ markers immediately after every image, binding the image to its original remote source and preserving non-owned editor attributes (alignment, dimensions, watermark, and unknown attributes).
• Resolve V2 markers by their bound source during draft updates, allowing changed Markdown image sources to safely retain original editor metadata.
• Reject corrupt, stale, duplicate, reused, or non-adjacent image markers.
• Continue supporting V1 image markers when the submitted image source resolves uniquely to a single remote image.

Dependencies

• Bump \pyjwt\ from 2.13.0 to 2.15.0 (#80).
• Bump \astmcp\ from 4.0.5 to 4.0.10 (#81).

Improved

• Modernize \pyproject.toml\ to PEP 621 metadata standard, eliminating Poetry 2 packaging warnings.

python-substack 0.9.0

Added

• Preserve image editor attributes through Markdown export and update with versioned image markers.
• Require explicit authorization for unmatched image replacements during draft updates.

v0.8.0

What's Changed

• Bump anyio from 4.13.0 to 4.14.2 in the pip group across 1 directory by @dependabot[bot] in #75
• feat: preserve Substack widgets in Markdown by @ma2za in #76

Full Changelog: v0.7.0...v0.8.0

0.7.0: Safe Markdown updates for supported drafts

---

layout: default
title: 0.7.0
parent: Releases

0.7.0

Added

• Add Api.update_draft_from_markdown(draft_id, markdown, ...) method to safely update draft content.
• Add substack drafts update DRAFT_ID MARKDOWN_FILE CLI command with --dry-run validation.
• Refuse to update drafts containing unsupported nodes to prevent remote data loss.
• Added --yes flag to bypass interactive confirmation for script usage.

Dependencies

• Bump fastmcp from 3.4.7 to 4.0.3 (#74).

0.6.0

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.

0.5.0

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).

python-substack 0.4.0

---

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

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

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.