Postpone Logo
Scheduling Posts

Mastodon

Schedule posts and threads to Mastodon and other ActivityPub servers

Mutation

Use the scheduleMastodonPost mutation to schedule posts to Mastodon:

Mutation
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
          media {
            id
            url
            type
          }
        }
      }
    }
  }
}

Input Parameters

ScheduleMastodonPostInput

username
String! required
The username of the connected Mastodon account to post from
postAt
DateTime! required
When to publish the post (must be in the future)
thread
[MastodonPostSubmissionInputType!]! required
Array of posts that make up the thread (minimum 1 post)
publishingStatus
PublishingStatusType
Publishing status. Options: READY_TO_PUBLISH, DRAFT (default: READY_TO_PUBLISH)
postTags
[ID!]
Array of post tag IDs to organize your content
id
ID
ID of existing post when updating (only for updates)

MastodonPostSubmissionInputType

Each post in the thread supports these parameters:

text
String! required
The post text content (max 500 characters by default, varies by server)
order
Int! required
Position of this post in the thread (0-based)
visibility
String! required
Post visibility. Options: PUBLIC, UNLISTED, PRIVATE, DIRECT
gallery
GalleryInput
Media attachments (images, videos, GIFs)
contentWarning
String
Content warning text (also called spoiler text)
language
String
ISO 639 language code for the post content
mediaName
String
Name of a file from your Content Library (case-insensitive)
mediaUrl
String
URL of media to upload and attach to the post
repostAtAmount
Int
Number of time units before auto-boosting
repostAtUnit
String
Time unit for auto-boost. Options: hour, day
repostRepeatDays
Int
How many days to repeat the auto-boost (max 365)
repostFromSocialAccount
SocialAccountInputType
Account to boost from (must be connected to your Postpone account)
removeAtAmount
Int
Number of time units before auto-deleting the post
removeAtUnit
String
Time unit for auto-deletion. Options: hour, day
removeMinLikes
Int
Minimum favorites required to prevent auto-deletion
final
Boolean
Whether this is the final post in the thread (default: false)
id
ID
ID of existing post when updating (only for updates)

Examples

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"
      }
    ]
  }
}

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",
        "mediaUrl": "https://picsum.photos/seed/socialmedia/900/1600"
      }
    ]
  }
}

Post with Content Library Media

Schedule a post using media already in your Content Library. The search is case-insensitive and will use the first matching file based on its name.

{
  "input": {
    "username": "myhandle@mastodon.social",
    "postAt": "2025-12-01T15:30:00Z",
    "thread": [
      {
        "text": "Sharing our company logo! 🏢",
        "order": 0,
        "visibility": "PUBLIC",
        "mediaName": "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
    }
  }
}

Validation Rules

The API enforces Mastodon's content policies and technical limitations:
  • 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

PUBLIC
String
Visible to everyone and appears in public timelines
UNLISTED
String
Visible to everyone but doesn't appear in public timelines
PRIVATE
String
Only visible to followers (followers-only)
DIRECT
String
Only visible to mentioned users (direct message)

Common Errors

Pinterest

Schedule pins to Pinterest boards

Tumblr

Schedule posts to Tumblr blogs