Which Mastodon instances work?
Any instance yeetpost can reach over https on a public address. The app is registered on your instance on demand the first time somebody connects an account there, and reused after that.
How to sendfrom
Follow these steps to connect Mastodon post, send from TypeScript, and track delivery.
Mastodon has no central developer app, so yeetpost registers itself on your instance the first time somebody connects an account there, and then sends you to that instance to approve posting. You type the host you are on, for example mastodon.social, and approve three scopes: read your account, write statuses, write media. No client id and no app registration of your own. In plain TypeScript this is a few lines in any Node process: a worker, a one-off script or a deploy step that already knows what to say.
What Mastodon takes
| How you connect | Your instance host, then approval on that instance for three scopes |
|---|---|
| Connection slug | mastodon for the first account, then a slug built from the handle |
| Text limit | Your instance's own limit, read when you connect. 500 by default |
| Images | Up to 4 per post, png, jpeg, gif or webp |
| Alt text | Yes, sent as each attachment's description |
| Threads | Yes, up to 24 replies under the head status |
| First comment | No, LinkedIn only |
| Scheduling | Yes |
| Permalink | Whatever your instance returned, in practice https://<host>/@<handle>/<status id> |
| Per-post fee | None |
1
Connect your platform
Connect your Mastodon account to yeetpost through your own instance:
- Go to app.yeetpost.com
- Click Add connection and select Mastodon
- Type the instance your account is on, for example
mastodon.social - Approve the request on your instance: yeetpost asks to read your account, write statuses and write media
The host has to be reachable over https and has to be a public address. Nothing else is needed from you: no client id, no client secret and no app registration of your own.
Paste your connection slug here and we'll auto-fill it into the code examples below.
2
Get your API key
Get your API key from the yeetpost dashboard:
- Go to app.yeetpost.com/app/settings
- Copy your API key
Paste your API key here and we'll auto-fill it into the code examples below.
3
Send your post
Install the yeetpost package:
npm install yeetpostExport your API key so the process can read it:
export YEETPOST_API_KEY=<your-api-key>Send a post:
import { yeetpost } from "yeetpost";
await yeetpost({
connection: "<your-connection-slug>",
text: "Hello from yeetpost!",
});To post to several connections in one call, use the JSON endpoint. It answers with one result per connection and accepts an Idempotency-Key, so a retry cannot double-post:
const response = await fetch("https://api.yeetpost.com/api/v2/posts", {
method: "POST",
headers: {
"x-api-key": process.env.YEETPOST_API_KEY!,
"content-type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
text: "Hello from yeetpost!",
connectionSlugs: ["<your-connection-slug>"],
}),
});
const { results } = await response.json();
for (const result of results) {
console.log(result.connectionSlug, result.status, result.url);
}Read each result.status rather than the HTTP status alone: one connection can fail while the rest go out.
4
Track your posts
Monitor all your posts from the yeetpost dashboard:
- Go to the Feed tab in the yeetpost dashboard
- View all posts sent via yeetpost, including status and timestamps
5
Review the security checklist
Review the Security Checklist to ensure your implementation is secure.
When a Mastodon post is refused
Each of these fails only the Mastodon item. Every other connection on the same request still goes out. The full vocabulary is in the errors reference.
| Code | Status | When |
|---|---|---|
| invalid_request | 400 | Text over the instance's limit, in the post or in any thread segment |
| media_unsupported | 400 | More than 4 images |
| shape_unsupported | 400 | A firstComment was given. Mastodon has no first comment |
| unauthorized | 401 | The token was revoked on the instance. Connect the account again |
| platform_rejected | 422 | The instance refused the image, is still processing it, or refused the status |
| internal_server_error | 500 | Our fault. Quote the req_id when you report it |
Mastodon FAQ
Why was my post refused when it fits my instance's counter?
Mastodon weighs every URL as 23 characters. yeetpost counts them in full, so a link-heavy status is refused a little sooner than the instance would refuse it. That direction is the safe one: nothing is published and then rejected.
What about content warnings, visibility and polls?
Not supported yet. A post goes out as a plain public status. Content warnings, visibility, polls and the language field are on the list, not in the product.
My token stopped working. What do I do?
Mastodon tokens do not expire and there is no refresh token, so a 401 means the token was revoked on the instance. Connect the account again in the dashboard.
Does the yeetpost package work outside Node?
It is a thin wrapper over the same HTTP endpoint, so anywhere you have fetch and can keep a secret it works. Do not run it in a browser bundle: the key would be readable by anyone loading the page.
Related guides
Related resources
Copy this guide (with your values) for use with LLMs or sharing with colleagues.