PostalAi for agents

PostalAi schedules social posts that assistants draft and the account owner approves. Every post waits for approval of its exact text before it can publish.

Connect

Add this MCP server URL to your client. It handles sign-in with OAuth (dynamic client registration and PKCE), and the owner approves the connection.

https://api.postal-ai.drawbuildplay.com/mcp

Connection details: /.well-known/mcp (MCP server card) and OAuth protected resource metadata. Access needs a PostalAi account enabled for assistants.

Rules

Tools

ToolWhat it doesHints
create_x_postSchedule an approved postidempotent, openWorld
create_x_postsSchedule several approved postsidempotent, openWorld
validate_x_postCheck a post before creating itreadOnly, idempotent
check_duplicateCheck whether text was already postedreadOnly, idempotent
upload_mediaUpload an image or video for a postopenWorld
get_x_postGet a scheduled postreadOnly, idempotent
list_x_postsList postsreadOnly, idempotent
cancel_x_postCancel a scheduled postdestructive, idempotent
reschedule_x_postMove a post to a new time, or schedule or edit a draftidempotent
whoamiWho am I posting asreadOnly, idempotent
approve_x_postApprove a post for publishing (needs the approve permission)destructive, idempotent, openWorld
reject_x_postReject a pending post (needs the approve permission)destructive, idempotent

Errors

Every error has code, error (what went wrong), hint (what to do next) and retryable (whether the same request can succeed later unchanged; retry those with backoff and the same Idempotency-Key).

CodeNext stepRetry
not_publishedOnly a post PostalAi published on 𝕏 can be deleted there. Cancel a scheduled post instead.no
already_deletedThe post is already deleted on 𝕏. Nothing more to do.no
delete_in_progressA delete for this post is already running. Read the post again in a minute.yes
x_refused𝕏 refused the delete. Ask the owner to reconnect the 𝕏 account in Postal.no
x_rate_limited𝕏 is rate limiting. Wait retryAfterSeconds, then try again.yes
x_partly_deletedPart of the thread is deleted on 𝕏 and the rest is not. The owner can tap Retry in Postal; it deletes only what is left.yes
x_unavailable𝕏 could not be reached and nothing changed. Try again shortly.yes
confirm_requiredOnly the owner can delete a post on 𝕏, in the Postal app, after confirming.no
not_media_holdThe post is no longer held for a media problem. Read it again before doing anything.no
media_missingThe media is gone from Postal. Upload it again with upload_media and create a new post, or ask the owner to cancel this one.no
invalid_actionSend action 'posted', 'post_now' or 'not_posted'. Only the owner can do this, in the Postal app.no
not_partialThis thread is not waiting on a failed reply. Read the post again; its replies may all be posted.no
retry_in_progressA retry of this thread is already running. Wait, then read the post again.no
not_unclearThe post is no longer waiting on an unclear outcome. Read it again before doing anything.no
read_failedPostal could not read the post. Ask the owner to try again in the app.no
write_failedPostal could not update the post. Ask the owner to try again in the app.no
unauthorizedSend a valid API key or OAuth token. Ask the owner to reconnect the assistant if it was revoked.no
invalid_keyThe API key is wrong or revoked. Ask the owner for a new key in PostalAi settings.no
insufficient_scopeThe key or connection lacks the permission this call needs. Ask the owner to grant it, then retry.no
not_allowedThis account cannot do this. Ask the owner.no
api_key_not_allowedPost now is only available to the signed-in owner in the PostalAi app.no
connection_not_allowedThis assistant may not post to that account. Use list_connections and pick an allowed connectionId.no
invalid_bodyFix the request body using the message, then send it again.no
invalid_argumentsFix the tool arguments using the message, then call the tool again.no
invalid_requestFix the request using the message, then send it again.no
missing_idempotency_keyAdd an Idempotency-Key header of 8 to 200 characters. Reuse it only when retrying the same request.no
missing_request_idAdd a requestId and reuse it only when retrying the same request.no
idempotency_conflictThis Idempotency-Key was already used for a different request. Use a new key for a new post.no
request_id_conflictThis requestId was already used for a different request. Use a new requestId.no
idempotency_post_missingThe post created for this key was deleted. Use a new Idempotency-Key to create it again.no
invalid_cursorDrop the cursor and start the listing from the first page.no
invalid_queryFix the query: count 1-20, minGapMinutes 0-1440, startHour 0-23 before endHour 1-24, weekdays 0-6, maxPerDay 1-50, days 7, 28 or 90.no
invalid_rangeSend from and to as ISO 8601 times with from before to.no
range_too_longAsk for a shorter time range and page through it.no
unknown_toolCall tools/list and use one of the listed tool names.no
method_not_allowedUse the HTTP method documented for this path in openapi.yaml.no
empty_textWrite some post text, then validate it again.no
text_too_longShorten the text to fit the limit in maxWeightedLength, or split it into a thread.no
thread_too_longUse fewer replies in the thread.no
article_emptyAdd a title and body to the article.no
article_too_longShorten the article body.no
link_not_allowedLinks are not allowed, except one 𝕏 post link (x.com/<handle>/status/<id>) as the last token. Remove other URLs, then validate again.no
duplicate_textThis text was already scheduled or posted recently. Change the wording or cancel the earlier post.no
approval_mismatchCall validate_x_post with the exact final post and send its textSha256 in approval.no
text_mismatchThe post text changed. Read the post again and send the textSha256 of its current text.no
media_mismatchThe attached media changed. Read the post again before deciding.no
poll_invalidSend 2 to 4 options of up to 25 characters and a duration of 5 minutes to 7 days.no
poll_with_mediaDrop either the poll or the media. X does not allow both on one post.no
media_not_foundUpload the file with upload_media first and use the mediaId it returns.no
media_duplicateList each mediaId once.no
media_requiredcontainsAiMedia needs media on the post. Attach the media, or drop containsAiMedia.no
media_too_manyAttach fewer media items. The message says the limit for this post type.no
media_type_unsupportedUse JPEG, PNG, WebP, GIF or MP4. Articles take images only.no
media_encodingSend the file bytes in data as base64.no
media_url_invalidPass a full https URL on the standard port, with no user or password in it.no
media_url_blockedUse a public https URL. Private, local and reserved addresses are refused, including after redirects.no
tagged_user_not_foundCheck the @handle spelling on 𝕏 (the account may be renamed, suspended or deleted) and drop or fix it.no
tag_lookup_unavailable𝕏 user lookup for photo tags failed; nothing was created. Retry shortly, or reconnect the 𝕏 account if it keeps failing.yes
media_too_largeImages up to 5 MB, GIFs up to 15 MB, videos up to 100 MB from a public https url (20 MB as base64 data). Compress the file or pass url.no
media_url_unreachableCheck that the URL opens the file directly (2xx, at most 3 redirects, under 20 seconds), or send the bytes in data instead.no
schedule_too_soonPick a later scheduledAt so the owner has time to approve.no
schedule_too_farPick an earlier scheduledAt.no
no_x_connectionAsk the owner to connect an X account in PostalAi.no
connection_not_foundCall list_connections and use one of the returned connectionIds.no
not_xThis call works with X connections only. Pick an X connection.no
not_foundCheck the id. It may have been deleted or belong to another account.no
unknown_topicPick a topic id from the current topic list. Merged topics are not accepted.no
not_pendingThe post was already decided. Read it to see its current status.no
approval_expiredThe approval window passed and the post was skipped. The owner can approve it late in Postal (now or a new time). Do not re-create it unless asked.no
not_reschedulableOnly pending or scheduled posts can be moved. Read the post to see its status.no
not_cancellableThe post already published or finished. Read it to see its status.no
thread_partialPart of the thread was posted. Read the post for which replies went out before doing anything else.no
rate_limitedWait retryAfterSeconds (or Retry-After), then retry with the same Idempotency-Key. Limits refill continuously, so waits are short.yes
loop_detectedToo many refused creates in 10 minutes. Stop resending; fix each refused request using its code and hint. Creates resume after retryAfterSeconds.yes
approval_limitThe daily approval limit was reached. Ask the owner to approve in the app, or retry tomorrow.yes
daily_ceiling_reachedThe account reached its daily post limit. Retry tomorrow.yes
too_many_pendingToo many posts are waiting for approval. Ask the owner to approve or reject some first.no
bulk_too_largeSend at most 20 posts per bulk call. Split the list and use a new Idempotency-Key for each call.no
same_url_too_soonAnother post on this account links the same URL less than 7 days from this time (postId). Pick a time at least 7 days apart, or link something else.no
duplicate_pendingA pending or scheduled post on this account has the same text. Change the wording, or cancel or move the other post (postId).no
retry_would_repostPostalAi cannot rule out that 𝕏 has this post (or part of its thread). Check the account on 𝕏; if it is not there, create a new post.no
too_closeAnother post on this account is scheduled less than 10 minutes from this time. Pick a time at least 10 minutes from it (postId).no
no_open_slotNo open slot in the next 7 days under the spacing rules. Pick a time with scheduledAt, or check find_open_slots with a wider window.no
duplicate_in_batchAnother post in this batch has the same text (ignoring case and spacing). Change the wording or drop one of them.no
too_close_in_batchThis post is scheduled less than 10 minutes from another post in this batch. Spread the times out, then send this post again with a new Idempotency-Key.no
too_many_draftsThis key has too many drafts. Schedule or cancel some first.no
not_editableOnly drafts can be edited. To change a pending post, cancel it and create a new one.no
too_many_keysRevoke an unused API key in PostalAi settings first.no
too_many_webhooksDelete an unused webhook first.no
invalid_urlUse a public https URL.no
unavailableA PostalAi dependency is briefly unavailable. Retry with backoff using the same Idempotency-Key.yes
media_storage_unavailableMedia storage is briefly unavailable. Retry with backoff.yes
internalSomething failed on our side. Retry with backoff using the same Idempotency-Key.yes

Machine-readable