For developers and AI assistants

Build on Postal

Everything in a Postal library is reachable from outside the app: tracks, tags, natural-language search, playlists, composers, analytics and briefs. Use the REST API from your own code, or connect an AI assistant through the hosted MCP server.

Read the docs↗Create an API key

Two ways in, one key

An API key from your Postal settings authenticates the REST API and is the credential you connect the MCP server with. Scopes on the key bound what either surface can do.

REST API

JSON over HTTPS

Cursor-paginated lists, scoped keys, signed webhooks and one metered endpoint: natural-language search over your whole library.

curl

curl https://api.postal.music/api/v1/tracks/search \
  -H "X-API-Key: $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "warm downtempo instrumental for a coffee ad",
    "limit": 5,
    "constraints": { "hasVocals": false, "bpmRange": [80, 100] }
  }'

API reference↗

MCP server

Your library in any AI assistant

A hosted Model Context Protocol server with 34 tools. Add it to Claude as a custom connector, or to Cursor and Claude Code by URL. Nothing to install.

mcp.json

{
  "mcpServers": {
    "postal": {
      "url": "https://mcp.postal.music/mcp"
    }
  }
}

Connect a client↗

What people build

Each recipe in the docs names the endpoints or tools it uses and the scopes the key needs.

REST API + WebhooksCatalogue syncKeep a label or publisher's system of record in step with Postal: ingest audio by URL, patch metadata, mirror composer and split records, and get webhooks back when analysis finishes.REST API + MCPSync and pitchingTurn a supervisor's brief into a shortlist with natural-language search, then ship it as a public playlist link in one more call.REST APITagging pipelineAuto-tag every upload, route low-confidence suggestions to a reviewer, and write corrections back so the model learns your catalogue.REST APIReportingWeekly engagement digests, top-track leaderboards per release, and read-only partner reporting across file requests.MCPAI assistantConnect Claude, Cursor or any MCP client and ask questions of your library, build playlists and tag tracks in conversation.All recipesBrowse use cases

What you can reach

The same objects you work with in the app, with the same permissions your key carries.

TracksList, upload by file or URL, edit details, find duplicates, trace submissions.SearchDescribe the music you need and rank the whole library against it.TagsFull taxonomy, AI suggestions, apply or correct. Corrections train the model.PlaylistsCreate, order and share. Public links come back ready to send.ComposersWriter, producer and publisher records with PRO and IPI.AnalyticsWeekly dashboard, per-track engagement, top-track rankings.BriefsCalls for submissions you own and everything that came in.WebhooksSigned callbacks when tracks, tags, composers and splits change.

MCP server

Ask your library instead of scrolling it

Once connected, an assistant chains the tools itself: search with hard constraints, build the playlist, hand back the link. Responses are compact by default so long conversations stay cheap.

Example prompts↗Tool reference↗

“Find five warm, mid-tempo instrumentals for a coffee ad and make me a playlist link.”
“Tag everything I uploaded this week and show me the suggestions you're least sure about.”
“Which of my tracks were played most this month, and where have they been submitted?”
“Are there duplicate files in my library I should merge before delivering to the distributor?”

Start building

Create a key in your settings, make your first request in five minutes, and read the full reference at docs.postal.music.

Open the documentation↗

One key works for both the API and the MCP server.