---
name: postmately
description: Schedule and publish social media posts (TikTok, YouTube, Telegram, VK page and communities, Pinterest, Bluesky, Mastodon) through Postmately; more networks open as each platform approves us. Use when the user asks to post, schedule, queue, draft or check social media content, or to upload an image or video for a post.
---

# Postmately

Postmately publishes posts to the social channels connected in the user's workspace. Every action goes through the Postmately API with
the user's API key.

## Setup

The user creates a key in Postmately under Settings > API. Keep it in the environment as
`POSTMATELY_API_KEY`, never print it or write it into files.

Prefer the MCP server when the agent supports MCP: `https://api.postmately.com/mcp`, header
`Authorization: Bearer $POSTMATELY_API_KEY`. The tools are `list_channels`, `validate_post`,
`import_media`, `list_media`, `create_post`, `update_post`, `reschedule_post`, `list_posts`,
`get_post`, `get_post_metrics`, `get_channel_insights`, `delete_post`, `get_analytics_overview`, `get_credits`,
`make_carousel`, `get_carousel`, `make_video`, `make_video_from_my_videos`, `start_phone_shoot`,
`get_shoot`, `get_video`, `list_plan_items`, `list_video_templates`, `list_image_packs`.

Without MCP, call the REST API (reference: https://api.postmately.com/openapi.json). REST covers channels, posts, media and metrics; carousel/video generation and the credit check are MCP-only:

```bash
curl -s https://api.postmately.com/v1/channels -H "Authorization: Bearer $POSTMATELY_API_KEY"
```

## Workflow

1. List channels first (`GET /v1/channels` or `list_channels`). Use only channels with
   `canPublish: true`. Read `rules`: `maxChars`, `mediaRequired` (`video`, `image` or `media`),
   `maxImages`, `maxVideos`.
2. Reuse files already in the workspace with `GET /v1/media` or `list_media`. For a new image or
   video, import its public link: `POST /v1/media` with `{"url": "..."}`. A local file can go up
   as `multipart/form-data` with a `file` field to the same endpoint. Keep the returned `id`.
3. Check the post before writing it: `POST /v1/posts/validate` or `validate_post`. It returns
   `{ "ok": true, "issues": [] }` or per-channel issues such as `media_required`, and writes nothing.
4. Create the post: `POST /v1/posts` or `create_post`

```json
{
  "text": "Three habits that fixed my sleep",
  "channels": ["<channelId>", { "id": "<youtubeChannelId>", "title": "3 sleep habits", "settings": { "visibility": "Public" } }],
  "mediaIds": ["<mediaId>"],
  "when": "draft"
}
```

   `when`: `"draft"` saves for review, `"next_slot"` takes the next free queue slot, `"now"`
   publishes immediately, or an ISO 8601 date-time with a time zone (`2026-10-01T18:00:00Z`).
5. Edit or move a draft or scheduled post with `PATCH /v1/posts/{id}` / `update_post`, or
   `POST /v1/posts/{id}/reschedule` / `reschedule_post`. Published posts cannot be edited.
6. Check the result with `GET /v1/posts/{id}` or `get_post`: each target has `status` (`pending`,
   `sending`, `sent`, `failed`), `url` of the published post, `error` and the latest `metrics`.
   For numbers use `get_analytics_overview` for all channels, `GET /v1/channels/{id}/insights`
   (or `get_channel_insights`) for one channel and `GET /v1/posts/{id}/metrics`
   (`get_post_metrics`) for one post. All three accept `days` (any whole number from 1 to 365)
   and return stored daily `history`; `metricsAvailable` says whether the network reports
   counters at all, and `metricsAt` says when the number was read. `metrics` stays null on
   networks without counters (TikTok, Telegram, LinkedIn, X, Google Business). Pinterest counters
   (`views`, `saves`, `clicks`, `linkClicks`) cover the last 90 days. Channel totals (`stats`) come from the platform, or from the latest
   daily snapshot when it does not answer.

## Carousels and videos

Call `get_credits` before generating. A carousel costs 20 credits, a
branded video 60, and an insufficient balance returns `insufficient_credits` with the needed
and available amounts.

- `make_carousel` takes a website link or a topic and renders 1080x1920 slides. It returns
  while rendering: poll `get_carousel` until `status` is `ready`, then pass
  `plan.caption + plan.hashtags` as the text and `renderedMediaIds` as media ids to `create_post`.
- `list_plan_items` shows the month plan; `list_video_templates` shows template slugs; `list_image_packs` shows photo pack ids for `make_carousel`. `make_video`
  queues a branded vertical video from a topic, a plan item, a template or a link to remake. Poll `get_video` until `state` is `ready`, then pass `video.id` to
  `create_post`.
- For the person's own footage, import the clips with `import_media` (public links) and call
  `make_video_from_my_videos`. Or call `start_phone_shoot`, give them the phone link, and cut
  it with `make_video_from_my_videos` after `get_shoot` shows every line filmed.
- A social network may still reject a carousel or video for its own format rules; use
  `validate_post` before publishing.
- If the agent already made the final images or video elsewhere, do not call `make_carousel` or
  `make_video`: `import_media` each file and pass the media ids to `create_post`. This spends no
  generation credits; storage still uses the plan's media quota.

## Rules

- Publishing is public and cannot be undone. Unless the user clearly said to publish or gave a
  time, use `"draft"` and tell them the post is waiting in Postmately.
- Fit each connected channel: Bluesky 300 characters, Mastodon 500, YouTube a video, Pinterest an image. TikTok accepts a video or a photo carousel of up to 10 images (the API cap). Use per-channel `text` overrides instead of cutting one text for all.
- TikTok Direct Post is live. Use `settings: { "postMode": "direct", "privacyLevel": "PUBLIC_TO_EVERYONE" }`
  when the owner asked for a public post; `postMode: "draft"` still works when they want to finish it in the
  TikTok app. Photo carousels are supported up to the API cap of 10 images, so a carousel can go to TikTok as well as a video.
- VK publishes to the page or the community of the channel. Photos and text go to the wall as a post. With a
  video, `settings: { "vkFormat": "clip" }` (the default) sends a vertical or square video up to 3 minutes to
  VK Clips, `"vkFormat": "video"` puts the video into a wall post.
- On a 400 with `error: "validation"`, read `issues` (one per channel), fix the input and retry.
- `DELETE /v1/posts/{id}` stops a scheduled post; it does not remove what is already published.