plan-and-schedule-campaign

Ayrshare MCP — Plan & Schedule a Campaign

A workflow skill that turns "schedule a week of launch posts" into a concrete, validated, scheduled set. There is no dedicated campaign or bulk tool: a campaign is a series of individual create_post calls, each with its own scheduleDate, each validated first. This skill is the planning and orchestration layer on top of ../post/SKILL.md.

It is built on the suggest-and-approve pattern: draft and validate everything, show the user the full plan, and only schedule after explicit confirmation.

The tools it orchestrates

• mcp__ayrshare__validate_post — dry-run each planned post against its platforms' rules before scheduling, so an over-limit caption or unsupported media is caught at planning time, not publish time.
• mcp__ayrshare__create_post — schedules one post by including a future scheduleDate (ISO 8601 UTC). Omitting scheduleDate posts immediately, so for a campaign every post carries one. Returns an id per post — capture them.
• mcp__ayrshare__get_post / mcp__ayrshare__update_post — inspect or edit a scheduled (pending) post afterward: reschedule, approve, or adjust. (See ../post/SKILL.md.)
• mcp__ayrshare__generate_post / mcp__ayrshare__recommend_hashtags — optional drafting aids for the copy (drafts only; they never publish). For on-brand copy, pair with ../draft-in-brand-voice/SKILL.md.

These are profile-scoped: choose the profile with the optional profileKey argument on each call or the connection's Profile-Key header (the argument wins when both are set). (generate_post/recommend_hashtags are the exception, with no profileKey argument; see ../generate/SKILL.md.) The whole campaign schedules under whichever profile you target, so settle that first and use it consistently across the posts.

Scheduling fields (from the post schema)

Per-post timing/workflow controls (full schema in ../post/references/create-post-schema.md):

• scheduleDate (ISO 8601 UTC, e.g. 2026-07-08T12:30:00Z) — the future publish time. The core of every campaign post. Convert relative dates ("next Tuesday 9am") to an absolute UTC timestamp yourself.
• autoSchedule ({ schedule: true, title? }) — publish into a named auto-schedule's next open slot instead of a fixed time. Cannot be combined with scheduleDate — pick one timing model per post.
• autoRepost ({ repeat: 1-10, days: >=2, startDate? }) — recurring/evergreen reposting (paid plan). Also cannot be combined with scheduleDate.
• requiresApproval (bool) — hold each post in awaiting approval until approved via update_post (approved: true). Useful when a human must sign off each calendar item.
• validateScheduled (bool, default true) — pre-validate scheduled posts at submission so errors surface immediately rather than at publish time. Keep it on.
• idempotencyKey (string) — unique per post so a retried submission does not create a duplicate. Worth setting when scheduling many posts in a loop.

Workflow

1. Confirm the profile. A campaign schedules under the profile you target, passed as the profileKey argument on each create_post (and validate_post), or via the Profile-Key connection header. If several profiles exist and none is given, ask which client this is for (see ../getting-started/SKILL.md).
2. Build the plan. Lay out the posts: for each, the message, the target platform(s), the media (if any), and the intended time. Adapt copy per platform (char limits, format) rather than reusing one string — use per-platform option objects where needed (e.g. youTubeOptions.title, redditOptions.title + subreddit). For drafting help, use ../generate/SKILL.md or, for on-brand copy, ../draft-in-brand-voice/SKILL.md.
3. Convert every time to ISO 8601 UTC. Turn "Friday 9am" into an absolute scheduleDate. Never pass a human phrase or an empty string. Decide one timing model per post: a fixed scheduleDate, OR autoSchedule, OR autoRepost — never two at once.
4. Validate every post. Call mcp__ayrshare__validate_post on each planned post (same inputs as create_post). Surface any per-platform issues and fix them before scheduling.
5. Show the full plan and get explicit confirmation. Present the calendar (each post: platforms, time, preview). Wait for the user to approve before scheduling anything. This is a write step — do not auto-schedule.
6. Schedule, one post at a time. For each approved post call mcp__ayrshare__create_post with its scheduleDate (set idempotencyKey). Capture the returned id for every post — that is how you manage it later.
7. Track and adjust. Use mcp__ayrshare__get_post to check status and mcp__ayrshare__update_post to reschedule/approve/edit a pending post. To recover a post that failed at publish time, use mcp__ayrshare__retry_post (once, only if retryable) — never a second create_post, which would duplicate.

Usage guidance

• A campaign is N individual posts. There is no bulk endpoint. You loop validate → create per post; the "campaign" is your plan plus the captured ids, not a single API object. Keep a running list of { time, platforms, id } so you can manage the queue.
• Validate before scheduling, not after. validate_post at planning time is the whole safety win — it turns publish-time rejections into planning-time fixes. Keep validateScheduled: true as well so scheduled posts are re-checked at submission.
• Confirm the whole calendar before any write. Show the user every post and time, get one explicit approval, then schedule. Suggest-and-approve, not fire-and-forget.
• One timing model per post. scheduleDate, autoSchedule, and autoRepost are mutually exclusive on a single post. Choose deliberately: fixed time for a calendar, autoSchedule for "next open slot", autoRepost for evergreen.
• Adapt copy per platform. Char limits and required fields differ (YouTube needs a title; Reddit needs title + subreddit). Build per-platform variants and validate each, rather than scheduling one identical string everywhere.
• Capture every id. Rescheduling, approving, editing, and status checks all key off the post id returned by create_post.
• Set idempotencyKey when scheduling in a loop. It prevents a retried submission from creating a duplicate scheduled post.

Gotchas

• No bulk/campaign tool exists. Don't look for one. Each post is its own validate_post + create_post. If you skip the per-post loop you'll under-deliver the plan.
• scheduleDate must be ISO 8601 UTC, future. e.g. 2026-07-08T12:30:00Z. A human phrase, an empty string, or a past time fails or posts immediately. Convert relative times yourself.
• scheduleDate + autoSchedule/autoRepost is invalid. They are mutually exclusive — combining them on one post is rejected. Pick one timing model.
• Scheduling is a write — never schedule without confirmation. Present the full calendar first. Don't auto-retry a failed schedule on a 4xx; a closed window, bad media, or wrong platform won't fix itself, and a blind resend can duplicate. Use idempotencyKey to be safe.
• Profile scoping: profileKey argument or Profile-Key header. The whole campaign schedules under whichever profile you target: the profileKey argument on each post (it wins) or the Profile-Key header. Settle it before scheduling for a client, and keep it consistent across the posts.
• Recover failures with retry_post, not a second create_post. A second create duplicates on platforms that already succeeded. retry_post re-attempts a failed post once, only if retryable.
• On any tool failure, call mcp__ayrshare__explain_error, then surface it. Translate the error to plain language for the user; a 429 gets at most one retry after a short delay. (Mirrors the global retry-safety rule in ../getting-started/SKILL.md.)