Mastodon
Mutation
Use the scheduleMastodonPost mutation to schedule posts to Mastodon:
mutation ScheduleMastodonPost($input: ScheduleMastodonPostInput!) {
scheduleMastodonPost(input: $input) {
success
errors {
field
message
}
post {
id
socialAccount {
id
username
}
publishingStatus
submissions {
id
text
order
postAt
visibility
contentWarning
language
gallery {
id
galleryMediaSet {
id
media {
id
url
mimeType
}
}
}
}
}
}
}
Input Parameters
ScheduleMastodonPostInput
schedulingMode: QUEUE_NEXT when scheduling a new post, or the post is a draft.
See Drafts without a date.SPECIFIC_TIME, QUEUE_NEXT (default: SPECIFIC_TIME).
Only accepted when scheduling a new post. See Scheduling at the Next Open Slot.READY_TO_PUBLISH, DRAFT (default: READY_TO_PUBLISH)MastodonPostSubmissionInputType
Each post in the thread supports these parameters:
PUBLIC, UNLISTED, PRIVATE, DIRECTid, name, or url. See Attaching Media.
Only supported when scheduling new posts, not when updating existing ones.hour, dayhour, dayExamples
Simple Post
Schedule a basic post with text only.
{
"input": {
"username": "myhandle@mastodon.social",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "Hello Fediverse! This is my first scheduled post 🚀",
"order": 0,
"visibility": "PUBLIC"
}
]
}
}
Scheduling at the Next Open Slot
Instead of picking a time yourself, pass schedulingMode: QUEUE_NEXT and leave postAt out. Postpone puts the post in the next open slot on the account's Account Schedule, skipping any slot that already has a post on it.
{
"input": {
"username": "myhandle@mastodon.social",
"schedulingMode": "QUEUE_NEXT",
"thread": [
{
"text": "This one goes out at my next open slot.",
"order": 0,
"visibility": "PUBLIC"
}
]
}
}
The whole thread lands on that one slot, the same way an explicit postAt applies to every post in the thread.
The account needs a schedule set up for this to work, postAt and QUEUE_NEXT can't be combined, and updateScheduledMastodonPost rejects schedulingMode. See Scheduling at the Next Open Slot for the full rules.
Post with Media URL
Schedule a post by uploading media from an external URL. The media will be automatically downloaded and added to your Content Library.
{
"input": {
"username": "myhandle@mastodon.social",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "Check out this amazing sunset! 🌅",
"order": 0,
"visibility": "PUBLIC",
"media": [{ "url": "https://example.com/sunset.jpg" }]
}
]
}
}
Post with Content Library Media
Schedule a post using media already in your Content Library. Reference the file by its id, which every upload mutation returns.
{
"input": {
"username": "myhandle@mastodon.social",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "Sharing our company logo! 🏢",
"order": 0,
"visibility": "PUBLIC",
"media": [{ "id": "1042" }]
}
]
}
}
You can also reference the file by name. Names are matched case-insensitively and the first match wins, so prefer id when several files share a name.
{
"media": [{ "name": "company-logo.png" }]
}
Thread with Multiple Posts
Schedule a multi-post thread.
{
"input": {
"username": "myhandle@mastodon.social",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "🧵 Thread about building great APIs (1/3)",
"order": 0,
"visibility": "PUBLIC"
},
{
"text": "First, always design your API with the developer experience in mind. Clear documentation and consistent patterns make all the difference.",
"order": 1,
"visibility": "PUBLIC"
},
{
"text": "Second, implement proper error handling and rate limiting. Your API consumers will thank you when things go wrong (and they will).",
"order": 2,
"visibility": "PUBLIC",
"final": true
}
]
}
}
Post with Content Warning
Schedule a post with a content warning (spoiler text).
{
"input": {
"username": "myhandle@mastodon.social",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "This is some sensitive content that might need a warning.",
"order": 0,
"visibility": "PUBLIC",
"contentWarning": "Sensitive topic discussion"
}
]
}
}
Unlisted Post with Language
Schedule an unlisted post with a specific language.
{
"input": {
"username": "myhandle@mastodon.social",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "Bonjour le monde! Ceci est un post en français.",
"order": 0,
"visibility": "UNLISTED",
"language": "fr"
}
]
}
}
Auto-Boost Configuration
Schedule a post with automatic boosting.
{
"input": {
"username": "myhandle@mastodon.social",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "Don't miss our latest blog post about API best practices! 📖",
"order": 0,
"visibility": "PUBLIC",
"repostAtAmount": 2,
"repostAtUnit": "hour",
"repostRepeatDays": 3,
"repostFromSocialAccount": {
"username": "mycompany@mastodon.social"
}
}
]
}
}
Response Types
Success Response
{
"data": {
"scheduleMastodonPost": {
"success": true,
"errors": [],
"post": {
"id": "123",
"socialAccount": {
"id": "456",
"username": "myhandle@mastodon.social"
},
"publishingStatus": "READY_TO_PUBLISH",
"submissions": [
{
"id": "789",
"text": "Hello Fediverse! This is my first scheduled post 🚀",
"order": 0,
"postAt": "2025-12-01T15:30:00Z",
"visibility": "PUBLIC",
"contentWarning": "",
"language": "",
"gallery": null
}
]
}
}
}
}
Error Response
{
"data": {
"scheduleMastodonPost": {
"success": false,
"errors": [
{
"field": "text",
"message": "You cannot schedule a post longer than 500 characters."
}
],
"post": null
}
}
}
Updating a Post
To update an existing scheduled post, use the same input type with the corresponding update mutation and include the post id:
mutation UpdateScheduledMastodonPost($input: ScheduleMastodonPostInput!) {
updateScheduledMastodonPost(input: $input) {
success
errors {
field
message
}
post {
id
}
}
}
Pass the id of the post you want to update in the input, along with the fields you want to change:
{
"input": {
"id": "12345",
"username": "myhandle@mastodon.social",
"postAt": "2026-01-15T10:30:00Z",
"thread": [{"text": "Updated toot text!", "order": 0}]
}
}
id field to specify which post to update. Only scheduled posts that have not been published yet can be updated.postAt is required on an update, so every update states the date the post goes out on — pass the date it already has to leave it where it is. A draft staying a draft is exempt, and a draft you're promoting to READY_TO_PUBLISH needs a date of your choosing; see Drafts without a date.
schedulingMode is not accepted on an update at all; see Scheduling at the Next Open Slot.
Validation Rules
- Text Length: 500 characters by default (varies by server), includes content warning text
- Media: Maximum 20 images per post, 1 video or GIF per post
- Images: PNG, JPG, HEIF, WEBP formats, maximum 16MB each
- Videos: MP4, M4V, MOV, WebM formats, maximum 99MB, max frame rate 120fps
- GIFs: Automatically converted to soundless MP4s, maximum 16MB
- Threads: No hard limit on thread length
- Scheduling: Posts must be scheduled for future dates only
- Visibility: Must be one of PUBLIC, UNLISTED, PRIVATE, or DIRECT
- Language: Must use valid ISO 639 language codes
- Account Limits: Respects your plan's monthly post limits
Visibility Options
Common Errors
The specified username is not connected to your Postpone account. Connect the account in your settings first.
The post text (including content warning) exceeds the server's character limit. Most Mastodon servers allow 500 characters.
The postAt timestamp must be in the future. Check your timezone settings.
A new post has to say when it goes out: pass a postAt, or schedulingMode: QUEUE_NEXT. Drafts are exempt: leave postAt off one and it is parked on a placeholder date about 30 days out.
schedulingMode isn't accepted on an update, so a postAt is the only way to say when the post goes out. You'll also see it when promoting a parked draft to publishingStatus: READY_TO_PUBLISH without giving it a date.
schedulingMode: QUEUE_NEXT needs an Account Schedule on the account you're posting to. Set one up, or pass an explicit postAt.
schedulingMode is only accepted when scheduling a new post. To move a post that is already scheduled, pass a postAt to updateScheduledMastodonPost.
The visibility must be one of: PUBLIC, UNLISTED, PRIVATE, or DIRECT.
The language code must be a valid ISO 639 language code (e.g., "en", "fr", "de").
Mastodon posts can have a maximum of 20 images or 1 video/GIF. Reduce the number of media attachments.
Images must be under 16MB and videos under 99MB. Compress your media files or use smaller versions.
You've reached your plan's post limit for the scheduled month. Upgrade your plan or schedule for a different month.