# JSON API

The app's screens also answer JSON, signed in with a personal access token.

Paste this into your agent:

> Show me my Mailpiece newsletter's latest posts through its JSON API. Read mailpiece.dev/docs/api.md first.

## Tokens and paths

Make a token under Profile › Personal access tokens and send it as a Bearer token. A read token is `GET` only; read and write can also create, change and delete.

Paths start with the newsletter's number, plus `.json`. `/my/identity.json` has no number and lists the accounts your token can reach.

```sh
curl -H "Authorization: Bearer $TOKEN" \
  https://app.example.com/834206594/posts.json

curl -H "Authorization: Bearer $TOKEN" \
  https://app.example.com/my/identity.json
```

## What answers JSON

Posts, with history, links and the published and sent lists. Subscribers, with a list per status: active, unconfirmed, unsubscribed, bounced and deactivated. Snippets, journeys, journey emails and search.

Settings: newsletter, handle, domain, sending, subscribe form, join code and welcome. Users, notification settings, your identity and access tokens.

## Marking a bounce

With a read and write token, an admin marks a subscriber bounced by id, or by address. Both answer `204`; an address or id the newsletter doesn't have answers `404`.

```sh
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://app.example.com/834206594/subscribers/$ID/bounce.json

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email_address": "reader@example.org"}' \
  https://app.example.com/834206594/subscribers/bounces.json
```

## From the CLI

The [CLI](https://mailpiece.dev/docs/agents) covers the whole API. `mailpiece api get`, `post`, `put` and `delete` reach any path with your saved token; `mailpiece commands --json` lists every command and flag.

Still need help? Ask on [GitHub](https://github.com/mailpiece/mailpiece).