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 Next.js, 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. From Next.js you call it through the yeetpost npm package, from a route handler, a server action or a scheduled job.
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 yeetpostSet your API key as an environment variable in .env.local. Keep it out of any name that starts with NEXT_PUBLIC_, because those are inlined into the browser bundle:
YEETPOST_API_KEY=<your-api-key>Send the post from a route handler, a server action or a scheduled job, never from a client component:
// app/api/announce/route.ts
import { yeetpost } from "yeetpost";
export async function POST(request: Request) {
const { text } = await request.json();
await yeetpost({
connection: "<your-connection-slug>",
text,
});
return Response.json({ ok: true });
}Deploying on Vercel? Add YEETPOST_API_KEY under Project Settings, Environment Variables, so the server build has it as well as your machine.
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.
Where should this run in a Next.js app?
On the server: a route handler, a server action or a cron job. The API key has to stay there, so read it from process.env and never put it behind a NEXT_PUBLIC name, which would ship it to the browser.
Related guides
Related resources
Copy this guide (with your values) for use with LLMs or sharing with colleagues.