Introduction

Scheduling Posts via API

The Postpone API provides powerful GraphQL mutations to schedule posts across multiple social media platforms. This comprehensive guide will walk you through the process of scheduling posts programmatically.

Overview

Postpone supports scheduling posts to the following platforms through dedicated GraphQL mutations:

Platform-Specific Mutations

Each platform has its own dedicated GraphQL mutation for scheduling posts. Here's a quick reference:

Common Parameters

While each platform has specific requirements, most scheduling mutations share common parameters:

Scheduling at the Next Open Slot

Instead of working out a time yourself, you can hand that job to Postpone: pass schedulingMode: QUEUE_NEXT, leave postAt out, and the post lands on the next open slot in the account's Account Schedule.

{
  "input": {
    "username": "myhandle",
    "schedulingMode": "QUEUE_NEXT"
  }
}

The rest of the input stays exactly as it was — only the date changes hands. Each platform page has a worked example.

A slot counts as taken when a scheduled post falls on it, or within about 30 minutes of it. Queue several posts in a row and they walk down the schedule one open slot at a time rather than piling onto the same time. The queue never fills up either: an account booked solid for months gets the first slot past the end of its queue.

This is the single-request version of querying Next Scheduled Dates and passing the result back as postAt. Prefer it over that two-step approach when you are only placing a post — because the slot is picked and taken in one transaction, two posts queued at the same moment can never be handed the same slot.

Rules

• A schedule is required. The account has to have an Account Schedule set up. Without one the mutation fails with <username> has no schedule set up.
• postAt and QUEUE_NEXT are mutually exclusive. Pass one or the other, never both. Sending both fails with Pass either a post date or QUEUE_NEXT, not both.
• New posts only. Update mutations reject schedulingMode outright — QUEUE_NEXT and SPECIFIC_TIME alike — with schedulingMode is not supported when updating a post. An already-scheduled post occupies a slot, so queueing it again would read that slot as taken and walk the post forward. To move a scheduled post, pass a postAt.
• Not for drafts. A draft doesn't hold a slot, so queueing one would hand the same slot to every other queued post. Save the draft without a date (or with a postAt), then set a date when you promote it to publishingStatus: READY_TO_PUBLISH.
• Reddit is not supported. scheduleRedditPost has no schedulingMode parameter — Account Schedules don't apply to Reddit. Pass a postAt on each submission.

Drafts without a date

A draft is somewhere to put a post before you've decided when it goes out, so postAt is optional on one:

{
  "input": {
    "username": "myhandle",
    "text": "still thinking about this one",
    "publishingStatus": "DRAFT"
  }
}

A date is still stored against the post, but it's a placeholder parked about 30 days out, not a time you chose.

Rules

• Drafts only. A post going out as READY_TO_PUBLISH still has to say when. Leaving postAt off one fails with Provide a post date, or use QUEUE_NEXT.
• Promotion needs a date. Promoting a draft to publishingStatus: READY_TO_PUBLISH without a postAt fails with Provide a post date. schedulingMode isn't accepted on an update either, so the date has to be spelled out.
• Editing doesn't need one. Updating a draft that stays a draft can leave postAt out; the draft stays parked. Pass a postAt to give it a real date at any point.
• A lapsed date gets re-parked. If a draft's stored date has passed by the time you edit it, a dateless edit pushes the placeholder back out. A date still in the future is never moved by an edit, whether you chose it or we parked it there.
• Reddit is not supported. scheduleRedditPost requires a postAt on each submission, drafts included.

Attaching Media

Scheduling mutations take a media parameter: a list of the images, videos, or GIFs to attach to the post. Each item points at a single file, in one of three ways:

Every item must set exactly one of id, name, or url, and no file can be attached to the same post twice. You can mix the three forms freely within one list:

{
  "media": [
    { "id": "1001" },
    { "name": "company-logo.png" },
    { "url": "https://example.com/images/hero.jpg" }
  ]
}

If a file can't be resolved, the whole mutation fails with an error rather than scheduling the post without it. The number of items you can attach depends on the platform, so check the platform-specific docs.

See Uploading Media for how to get files into your Content Library and pick up their id.

Deprecated Media Parameters

mediaUrl, mediaUrls, and mediaName are deprecated in favor of media. They still work, but new integrations should use media, and existing ones should migrate:

Response Format

All scheduling mutations return a consistent response structure:

{
  success: Boolean!
  errors: [ValidationError]
}

Common Errors

These errors are commonly encountered across multiple platforms when scheduling posts:

Best Practices

When using the scheduling API, keep these best practices in mind:

Getting Started

To begin scheduling posts via the API:

Next Steps

Ready to start scheduling posts? Choose a platform from the list above to see detailed examples and platform-specific requirements.