Substack Direct Subscribe — WordPress

Collect email subscriptions to your Substack publication directly from your WordPress site — no server required.

Substack blocks API requests from cloud / datacenter IPs (Vercel, Netlify, AWS, etc.). Standard server-side POSTs fail silently. This plugin works around it by sending the subscribe request from the visitor's browser — a real user IP — using fetch with mode: "no-cors". Zero backend, zero webhooks, zero proxy.

Features

Shortcode	[substack_subscribe ...] anywhere — posts, pages, widgets, templates
Gutenberg block	"Substack Subscribe" with full sidebar settings panel
Popup modal	Timed popup with configurable delay, dismissed per session
Two layouts	card (centered, emerald accent) and banner (inline, transparent)
Four visual states	idle → submitting (spinner) → success / error
Zero server storage	No email data touches your WordPress database or logs
Privacy-first	Fully GDPR-friendly — requests go direct to Substack, not through your server

Installation

From WordPress admin

1. Download the latest release .zip
2. Go to Plugins → Add New → Upload Plugin
3. Choose the .zip file and click Install Now
4. Activate the plugin

Manual

1. Upload the substack-direct-subscribe-wp folder to /wp-content/plugins/
2. Activate via Plugins in WordPress admin

Usage

Shortcode

[substack_subscribe substack_url="https://yourpub.substack.com" publication_id="123456"]

Attributes

Attribute	Default	Required	Description
substack_url	—	Yes	Your Substack publication URL
publication_id	—	Yes	Your Substack publication ID
layout	card	No	card or banner
align	center	No	left, center, or right
full_width	false	No	true or false

Examples

[substack_subscribe substack_url="https://example.substack.com" publication_id="123456"]

[substack_subscribe substack_url="https://example.substack.com" publication_id="123456" layout="banner" align="left"]

[substack_subscribe substack_url="https://example.substack.com" publication_id="123456" full_width="true"]

Gutenberg Block

1. Open the block inserter ( + button)
2. Search for "Substack Subscribe"
3. Configure URL, Publication ID, layout, alignment, and full width in the block sidebar (Settings → Block)

Popup (timed modal)

1. Go to Settings → Substack Subscribe in the WordPress admin
2. Enter your Substack URL, Publication ID, and delay in minutes
3. The popup will auto-appear for visitors after the configured delay

Visitors who successfully subscribe are remembered via localStorage (never shown again). Dismissals are stored in sessionStorage (per browsing session). Logged-in editors never see the popup.

Programmatic trigger

Add data-substack-popup to any element to open the popup on click:

<button data-substack-popup>Subscribe to Newsletter</button>
<!-- or -->
<a href="#" data-substack-popup>Join our mailing list</a>

Finding your Publication ID

1. Go to your Substack dashboard
2. Open browser DevTools → Network tab
3. Sign up a test email on your Substack site
4. Look for the POST request to /api/v1/free
5. Find the landingPublicationId field in the request payload — that's your ID

Alternatively, inspect the subscribe button HTML on your Substack publication — the data attribute often contains the ID.

How it works

sequenceDiagram
    Visitor->>Browser: Clicks Subscribe
    Browser->>Substack API: POST /api/v1/free (mode: no-cors)
    Substack API-->>Browser: 200 OK
    Browser->>Visitor: Shows success state
    Note over Browser,Substack API: Request originates from visitor's IP

The form sends three fields to Substack's API:

Field	Value
email	The subscriber's email address
first_url / current_url	Page URL where the subscription happened
landingPublicationId	Your Substack publication ID

Substack processes the subscription and sends a standard confirmation email. No data touches your server, no confirmation comes from you.

Styling

The plugin ships with clean, minimal CSS. All styles are prefixed with .sds- to avoid conflicts. To customize:

• Override via theme CSS — use the same .sds-* selectors with higher specificity
• Copy and modify — copy the form markup from substack-direct-subscribe.php:91-159 into your theme and style freely
• Full-width banner — great for footer areas, uses a transparent background with white text

Development

substack-direct-subscribe-wp/
├── substack-direct-subscribe.php    # Plugin bootstrap: shortcode, block, popup
├── assets/
│   ├── css/style.css                # Form and popup styles
│   └── js/script.js                 # Client-side form handler (vanilla JS)
├── src/
│   ├── admin.php                    # Settings page (Settings → Substack Subscribe)
│   └── block.js                     # Gutenberg block registration
├── README.md
└── .gitignore

Requirements

• WordPress 5.8+
• PHP 7.4+
• No additional dependencies — all JavaScript is vanilla, no build step required

Changelog

1.0.0

• Initial release
• Shortcode [substack_subscribe] with 5 configurable attributes
• Gutenberg block with full sidebar settings
• Timed popup with admin settings page
• Card and banner layout variants
• Idle / submitting / success / error visual states
• Programmatic popup trigger via data-substack-popup

License

MIT — see LICENSE for details.

---

Built by Tomi Abe