Substack by Cotlet

Add one email to your list as a free subscriber. Adds one email as a free subscriber, the same as Add subscribers in the dashboard, and Substack sends its usual welcome email. Substack adds the email in the background, so list_subscribers may show it a minute later. Add only people who agreed to hear from you.

Stop a scheduled post from going out; it stays as a draft. Removes the scheduled time from a post, so nothing is published or emailed then; the post stays a draft with its content. Schedule it again with schedule_post. A post with no schedule returns an error.

New draft from Markdown. Nothing is sent until you publish or schedule it. Creates a draft in your publication and returns its post_id and editor link. Markdown covers headings, paragraphs, bullet and numbered lists, quotes, code blocks, rules, images by public URL, bold, italic, strikethrough, inline code and links; local image files cannot be used. Sending is a separate step: schedule_post or publish_post. A draft reaches no one, so it runs without asking.

New tag for grouping your posts. Creates a post tag on your publication; Substack makes the slug from the name. A tag with no posts shows nowhere. Put posts under it with tag_post.

New private tag for grouping subscribers. Creates a subscriber tag on your publication. Tags are private: subscribers never see them. Put subscribers under it with tag_subscribers.

Delete one of your own comments, Notes or Note replies. Deletes something you wrote: a comment under a post, a Note or a reply to a Note. Replies other people wrote under it stay, under a deleted placeholder. Someone else's comment returns an error; on your own posts remove it with remove_comment.

Delete a draft, scheduled or published post, with its comments. Deletes one post of your publication for good: a draft, a scheduled post (its send is cancelled) or a published post, which leaves the web, the archive and the app with its comments and stats. Emails already sent stay in inboxes. Substack has no undo; unpublish_post keeps the post as a draft instead.

Copy any post into a new draft. Makes a new draft with the title, subtitle, body and settings of a draft or published post, as Duplicate in the post list does. Substack puts [COPY] in front of the title; change it with update_draft. Nothing is published or sent.

The full subscriber list as a CSV download link, with the row count. Builds the same CSV as Export in the subscriber dashboard: email, name, subscription type, activity rating and start date. Substack builds the file in the background; the call waits up to about a minute and otherwise asks you to try again later. The link needs no sign-in and works until expires_at, 24 hours when we recorded it. For filtered pages use list_subscribers.

Takes no parameters.

Follow or unfollow a Substack user, so their Notes reach your feed. Follows a person on Substack, as Follow on their profile does, or unfollows them. Following is not subscribing: you get their Notes and activity in the app, not their newsletter by email. They see the follow.

Where your subscribers live, and which publications share your readers. Returns Analytics > Statistics > Audience: subscriber counts per country (region world, ISO codes such as us, gb) or per US state (region usa, codes such as ny, ca), all subscribers or paid only, the number of countries and states with any subscriber, and the publications whose readers overlap most with yours. Substack computes these in the background; a new publication has empty lists for a while.

The latest messages of one direct-message conversation, oldest first. Returns who is in the conversation and its latest messages as the chat window first shows them, oldest first, with sender, text and time. Opening a conversation this way marks nothing read.

Day by day: total and paid subscribers, followers and views. Returns one row per day of the period, as the charts on the dashboard home and in Audience: total subscribers, paid subscribers and followers at the end of the day, and the day's views across your site and the app. Days Substack has no number for are null; a young publication starts on the day it was made.

Your Substack home feed: posts and Notes, For you or Following. Returns one page of the home feed of the Substack app, split into posts and Notes in feed order. for_you is Substack's own mix; following holds only people and publications you follow or subscribe to. Suggestions of people to follow are left out. Reading marks nothing seen. Page with next_cursor; the feed is personal and changes between calls.

Full post: title, subtitle, body as Markdown, audience, URL and dates. Returns one post of your publication, draft, scheduled or published, with its full body as Markdown, including the paywalled part. Images come back as URLs. Buttons, embeds and footnotes come back as plain text, so writing the body back with update_draft drops them. A scheduled post also has publish_at.

Who liked and commented on a post, and the subscribers it won and lost. Returns the Engagement and Growth parts of a post's stats: like and comment counts with the people behind them (name and handle, never email), and the free signups, paid subscriptions and unsubscribes Substack credits to the post. Counts keep changing for days after a send.

Recipients, opens, open rate, views, likes, restacks and subscribers gained. Returns the engagement numbers of one published post, as on its stats page in the dashboard. Email numbers cover the send; views include the web; likes are reactions. A draft or scheduled post returns an error. Numbers keep growing for days after a send, so check again later.

Where a post's readers came from: sources, categories and devices. Returns the Traffic part of a post's stats: each source (app, email, a website, search) with its views, share of all views and the free and paid subscribers it brought, the share per source category and per device. A post nobody has read yet returns empty lists.

Total and paid subscribers, new subscribers, paid cancellations and estimated revenue for a period. Totals are from the publisher dashboard at the end of the period (7, 30 or 90 days). subscribers_churned counts paid cancellations only; Substack keeps no count of free unsubscribes. subscribers_new is the growth in total subscribers plus those cancellations. revenue_usd is not money received: it is the dashboard's annualized revenue at the end of the period, times the period's share of a year.

How many unread direct messages, message requests and activity notifications you have. Returns the badges of the Substack app: unread direct messages, pending message requests and unread activity (likes, replies, new followers, restacks). Reading them marks nothing read.

Takes no parameters.

Like or unlike a comment or a Note as you. Adds your heart to any Note or Note reply, or to a comment under a post of your publication, or removes it with unlike. Comments and Notes share one ID space, so a Note ID from list_notes or search_substack works too. The author sees your like in their activity.

Like or unlike any Substack post as you. Adds your heart to a post on any publication, as the heart under a post does, or removes it with unlike. The author sees your like in their activity. Liking twice keeps one like.

Your Substack notifications: replies, likes, new followers, restacks, newest first. Returns the Activity tab of the Substack app, newest first. type is Substack's own name, e.g. note_reply, note_like, comment_reply, comment_like, post_like, follow, restack or mention. from lists the latest people behind a grouped item and people counts all of them. A reply or mention carries its comment_id and text; on_comment_id and on_post_id point at what it was about. Reading the list marks nothing read. Page with next_cursor.

Comments on a post, with author, text and whether you replied. Returns all comments of one post at once, oldest first, with replies nested under their parent. Deleted comments are left out. replied is true when you answered anywhere in the thread under the comment; unanswered_only keeps only top-level comments where you did not. Pass comment_id to reply_to_comment.

Your direct-message conversations, latest first, with the last message. Returns your Substack chat inbox: one-to-one and group direct messages with who they are with, the last message, its time, your unread count and whether it is a message request from someone you do not follow. Publication chats are left out. Reading the list does not mark anything read. Pass conversation_id to get_conversation or send_message.

Replies under a Note, with author, text and likes. Returns the direct replies under one Note (yours or anyone's), in Substack's order. replies is the count under each reply; list those by passing its note_id. Substack sends no handle with replies, so author.handle is empty and url is null. Page with next_cursor.

Notes posted by you or any other Substack user, newest first, with likes and replies. Returns the Notes on a profile's Notes tab, newest first: text, time, likes, restacks, reply count and link. Without user it lists yours. Posts and restacks of posts on the profile are left out. Page with next_cursor. Pass note_id to list_note_replies, like_comment or reply_to_note.

Tags your publication uses to group posts. Returns every post tag of your publication with its ID, name and slug; readers see tagged posts on /t/{slug}. hidden tags group posts without a public page. Pass tag_id to tag_post.

Takes no parameters.

Posts of your publication, newest first, with status and audience. Lists posts of your publication, newest first. Filter by status to see drafts or scheduled posts. Scheduled posts include their publish time. Pages hold up to 50 posts; pass next_cursor back as cursor for the next page.

Publications you recommend, or that recommend you, with the subscribers each sent. Returns Audience > Recommendations: with direction given, the publications you recommend; with received, the ones recommending you, and whether you recommend them back (mutual). subscribers_sent counts subscribers the recommendation brought. The table is rebuilt by Substack in the background, so a recommendation made minutes ago may be missing while counts already include it; publication_id checks one recommendation of yours directly.

Sections of your publication, the separate newsletters inside it. Returns each section with its ID, name, description and slug. live is false while Substack still sets a new section up. subscribed_by_default tells whether new subscribers get its emails. A publication without sections returns an empty list.

Takes no parameters.

Tags you use to group subscribers. Returns the subscriber tags of your publication with their IDs, as Audience > Subscribers > Tags shows them. Subscribers never see tags. Pass tag_id to tag_subscribers.

Takes no parameters.

Subscribers with plan, start date and activity rating. Lists subscribers, newest first, from the subscriber dashboard. Activity rating is the 0 to 5 score Substack shows there. Pages hold up to 500 rows; pass next_cursor back as cursor. The plan and since filters apply inside each page, so a filtered page can be short or empty while next_cursor still points further. Someone added a minute ago may not show yet: Substack fills the table in the background. paid includes founding members.

Publications you subscribe to, with your plan and whether their emails reach you. Returns every publication your account subscribes to, as Settings > Subscriptions lists them: name, link, plan (free, paid, comp, founding or gift, as Substack names the membership) and whether you get its emails. Your own publications are left out.

Takes no parameters.

Where your publication's visitors came from in a period, most views first. Returns Analytics > Traffic > Traffic sources: each source (the app, email, a website, search, social) with its category, views, unique visitors and the free and paid subscribers it brought. Sorted by views; page with next_cursor.

Pin a comment to the top of your post's comments, or unpin it. Pins one comment on a post of your publication above all others, as Pin in the comment menu does, or unpins it. A comment on someone else's post returns an error.

Short post in Substack Notes, now or at a set time, optionally with a link card to one of your posts. Posts a Note under your name. Without publish_at it goes out now; with it, the Note waits in your scheduled Notes, status is scheduled and published_at is that time. Text is 1 to 1,000 characters. link_post_id must be a published post.

Publish a draft now. Publishes a draft immediately, on the web and, unless send_email is false, by email, to the audience set on the draft. Substack's own pre-publish check runs first; a missing title or an empty body stops the call. A sent email cannot be recalled. On a publication with sections the post goes to section_id, else to the section already set on the draft, else to the main publication.

Recommend another publication to your readers, or stop recommending it. Adds a publication to your Recommendations, as Growth > Recommendations does: Substack suggests it to people who subscribe to you and notifies its author. blurb is the short reason readers see. With remove it takes the recommendation back.

Remove someone's comment from your post as the publication's moderator. Hides a comment on a post of your publication, as Remove in the comment menu does: readers see that a moderator removed it, the text is gone, replies under it stay. Use delete_comment for your own comments. A comment on someone else's post returns an error.

Remove one email from your subscriber list. Removes a subscriber from your list, as Remove in the subscriber's menu does: they get no more emails from you and no notice. A paid subscription is cancelled and Substack refunds the unused part. An email not on your list returns an error; add_subscriber takes about a minute before the address is listed.

Reply as you under a comment on your post. Posts a reply under one comment on a post of your publication, under your name, visible to everyone who can read the post. A comment elsewhere on Substack returns an error. The author gets Substack's usual reply notification.

Reply as you under any Note or Note reply. Posts a reply under a Note (yours or anyone's) or under a reply to one, visible to everyone who sees the Note. Text is 1 to 1,000 characters; Markdown bold, italics and links work. The author gets Substack's usual notification.

Publish a draft at a set time, on the web and by email. Schedules a draft to go live at the time you set, on the web and, unless send_email is false, by email, to the audience set on the draft. The time needs a time zone and must be in the future. Substack's own pre-publish check runs first; a missing title or an empty body stops the call. A scheduled post stays editable until it goes out. On a publication with sections the post goes to section_id, else to the section already set on the draft, else to the main publication.

Search all of Substack for people, posts and Notes. Runs Substack's search as the search box does and splits the results into people, posts and Notes. Use the IDs with follow_user, like_post, like_comment, reply_to_note, send_message or recommend_publication. Page with next_cursor; later pages may hold only posts and Notes.

Send a direct message on Substack, in a conversation or to a person. Sends a private chat message under your name. With conversation_id it replies there; with user it writes to that person, in your existing conversation with them or a new one. Someone who does not follow you gets it as a message request. Give one of conversation_id or user. A sent message cannot be recalled.

Add a tag to a post, or take it off. Puts one of your post tags on a draft or published post, or removes it with remove. A post can have several tags. Tagging twice keeps one tag.

Put a tag on subscribers by email, or take it off. Adds one of your subscriber tags to up to 50 subscribers, or removes it with remove. Emails not on your list come back in not_found and nothing else fails. A subscriber added a minute ago may not be findable yet; try again shortly.

Take a published post off the web and back to drafts. Turns a published post back into a draft, as Unpublish in the editor does: it leaves your site, archive and the Substack app, and its link stops working. Comments and stats stay with the draft. Emails already sent stay in inboxes. Publish it again with publish_post. A post that is not published returns an error.

Change the title, subtitle, body or audience of a draft. Changes the fields you pass and leaves the others as they are. body_markdown replaces the whole body. Drafts and scheduled posts only: a published post returns an error. Nothing reaches your subscribers, so it runs without asking.