The Marketing Plan API lets you generate and manage an AI-powered social media marketing plan for a site. A marketing plan is a schedule of marketing activities, such as social campaigns, blog posts, and emails, that the AI tailors to the site's business, goals, and content calendar. For each activity you can generate ready-to-publish social posts and schedule them through the site's connected channels.
With the Marketing Plan API, you can:
- Generate and regenerate an AI marketing plan of scheduled activities.
- Generate social posts (an image and per-channel captions) for activities and schedule them for publishing.
- Manage the individual activities in a plan.
- Add custom calendar events, such as sales, holidays, and product launches, that shape the generated plan.
- Configure marketing settings, such as the goal, channels, tone, and posting frequency, that drive generation.
The Marketing Plan API is organized into the following services:
- Marketing Plan - generate and regenerate the plan, generate and schedule its social posts, and retrieve the plan and its activities.
- Marketing Activities - retrieve and manage the individual activities that make up a plan.
- Calendar Events - manage custom events that give the AI extra context when it generates a plan.
- Marketing Settings - configure the preferences that shape how the AI generates the plan and its posts.
Plan and post generation runs asynchronously. The generate and regenerate methods return immediately with a status of GENERATING and continue the work in the background. To learn when generation finishes, poll GetSocialMarketingPlan until status is ACTIVE (ready) or FAILED. To learn when an activity's posts are ready, poll GetMarketingActivityPosts.
A generated plan schedules marketing activities from today through the end of next month. Social posts, however, are generated automatically only for the nearest-term activities; how far ahead that reaches can depend on the site's social marketing premium plan. To generate posts for the remaining activities, call GenerateSocialPosts with their activity IDs. Posts are created as drafts that are managed by the Publisher API, and you schedule them for publishing with ScheduleDrafts.
Posts are generated for all supported social channels, so the API returns posts for channels the site hasn't connected too. Only posts for connected channels (connected through the Publisher) can be scheduled and published; posts for unconnected channels stay as drafts.
To refresh an existing plan, call RegenerateMarketingPlan. If you've changed the content pillars (the topics in the marketing settings), call RegenerateMarketingPlanWithKeywordResearch instead: it runs fresh SEO keyword research to update the plan's blog activities, and takes longer.
It's important to note the following points before starting to code:
- The site should be published before you generate a marketing plan, because generation draws on the published site. This isn't validated at call time: an unpublished site results in either a
FAILED status or an ACTIVE plan with no generated posts. Verify the site is published before generating.
- Generation is asynchronous and non-deterministic. The generate methods return a
status of GENERATING, and results differ between runs. Poll for completion rather than relying on the immediate response.
- Marketing settings are optional. If a site hasn't configured them, sensible defaults are applied at generation time. To customize the output, upsert the settings before generating. Social marketing must be enabled in the settings for posts to be generated automatically when a plan is created.
- To schedule or publish a post, the site owner must connect that channel through the Publisher. Posts for channels that aren't connected stay as drafts.
- Settings shape the plan only when it's generated. After changing a setting that affects the plan, regenerate it for the change to take effect. The site's language and location are derived from the site itself, not set through this API, and likewise apply on the next generation.
- Marketing plan: A per-site, AI-generated schedule of marketing activities covering today through the end of next month. A site has at most one plan at a time.
- Marketing activity: A single planned marketing action within a plan, such as a social campaign, blog post, or email, with a title, description, and target date.
- Post: Social content (an image and a channel-specific caption) generated for a marketing activity. Posts are created as drafts and can be scheduled for publishing.
- Draft: A post that has been created but not yet scheduled or published.
- Calendar event: A custom event a site owner adds to the marketing calendar, such as a sale or holiday, that gives the AI context when generating the plan.
- Marketing settings: A site's preferences, such as goal, channels, tone, and posting frequency, that shape how the AI generates the plan and its posts.
- Content pillars: Recurring themes or topics the plan's content is built around.