Socials

Socials lets your agent post on your behalf to the accounts you connect: X, LinkedIn, Instagram, TikTok, Facebook, Threads, Pinterest, YouTube, and Bluesky. You connect accounts once in the console; the agent writes, schedules, and publishes — and reads back per-platform results with live URLs.

Socials is in admin preview. It's merged and documented, but only enabled for admin accounts while we finish hardening it.

How It Works

Connect:  Human connects accounts in the console (Integrations page)
Post:     Agent calls social.posts.create → published to selected accounts
Check:    Agent polls the post → per-platform results + live URLs

Connecting uses secure hosted OAuth — your social platform credentials never touch Mailgent.

Connecting Accounts Is Console-Only — By Design

Humans connect accounts at console.mailgent.dev → your project → Integrations. Agents cannot initiate connections — there is no API endpoint for it. That's deliberate: an agent should never be able to expand its own reach to a new platform. The human decides which accounts exist; the agent decides what to post to them.

Posting Is Asynchronous

POST /v0/social/posts accepts the post and returns immediately with a postId and status: "processing" (or "scheduled"). Platforms publish at their own pace — poll GET /v0/social/posts/:id for per-platform results and the live post URLs. Each post consumes 1 credit.

Target accounts three ways:

Omit both accountIds and platforms — post to all connected accounts.
platforms: ["x", "linkedin"] — post to every connected account on those platforms.
accountIds: [...] — post to exactly those accounts (ids from GET /v0/social/accounts).

Add mediaUrls for images/video and scheduledAt (ISO-8601) to publish later.

Scopes

Scope	Allows
`social:read`	List connected accounts, list posts, check post results
`social:write`	Create and schedule posts

MCP Tools

Tool	Scope	Description
`social_list_accounts`	`social:read`	Connected accounts with platform and username
`social_get_post`	`social:read`	Post status, per-platform results, live URLs
`social_post`	`social:write`	Publish or schedule a post

API Endpoints

Method	Path	Scope	Description
`GET`	`/v0/social/accounts`	`social:read`	Connected social accounts
`POST`	`/v0/social/posts`	`social:write`	Create a post `{text, accountIds?, platforms?, mediaUrls?, scheduledAt?}`
`GET`	`/v0/social/posts`	`social:read`	List your posts, newest first
`GET`	`/v0/social/posts/:id`	`social:read`	Post status + per-platform results and live URLs

Example: Publish a Post

curl -X POST https://api.mailgent.dev/v0/social/posts \
  -H "Authorization: Bearer mgnt-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "We just shipped agent-native payments. Thread below 🧵",
    "platforms": ["x", "linkedin"]
  }'

Returns 201 with the post id and the accounts it's going to:

{
  "postId": "post_abc123",
  "status": "processing",
  "accounts": [
    { "id": "sa_1", "platform": "x", "username": "mailgent" },
    { "id": "sa_2", "platform": "linkedin", "username": "mailgent" }
  ],
  "message": "Posting is asynchronous — poll GET /v0/social/posts/:id for per-platform results."
}

Example: Check Results

curl https://api.mailgent.dev/v0/social/posts/post_abc123 \
  -H "Authorization: Bearer mgnt-your-api-key"

Returns the post plus per-platform results — success/failure per account and the live URL of each published post.

Security

Secure hosted OAuth — your social platform credentials never touch Mailgent.
Console-only connections — agents cannot connect, reconnect, or disconnect accounts.
Identity-scoped — an identity can only post to accounts its human connected to it.
Audit trail — every connection and post shows up in the activity log.

On this page