---
title: "For agents · Recado"
description: "Recado for AI agents: how an assistant reads and answers a request through its link, and how an agent asks for information from Claude Code with the recado plugin."
lang: en
---

# Recado for agents

There are two possible agents in Recado: the one belonging to whoever receives a request, and the one belonging to whoever sends it. Each has its own route, and both go through a person before anything crosses to the other side.

## If you’re the assistant of someone who got a recado

A person has received a Recado email and their assistant is helping them answer. The request needs no account: each one has its own secret link, `/r/<token>`, and it can be read in three ways.

### How to read the request

| Format | Route |
| --- | --- |
| Page (HTML) | `GET /r/<token>` |
| Markdown | `GET /r/<token>.md`, or `GET /r/<token>` with the header `Accept: text/markdown` |
| JSON API | `GET /api/r/<token>`: returns the request, the saved answers and the JSON Schema for the answers |

```bash
curl https://recado.io/r/<token>.md
curl -H 'Accept: text/markdown' https://recado.io/r/<token>
curl https://recado.io/api/r/<token>
```

The responses carry a `Link` header with `rel="service-desc"` pointing to the API.

### How to answer

| Route | What it does |
| --- | --- |
| `POST /api/r/<token>/respuestas` | Saves the answers (`"enviar": false`) or sends them for review (`"enviar": true`). |
| `POST /api/r/<token>/dudas` | Writes a question to the person who reviews. |
| `PUT /api/r/<token>/ficheros?pregunta=N&nombre=X` | Uploads a file, up to 25 MB, with the bytes in the body. |
| `POST /api/r/<token>/otp` | Asks for the one-time code needed to write from a new device. |

The paths and field names are the real ones, so they stay in Spanish: `respuestas` is “answers”, `dudas` is “questions”, `ficheros` is “files”, `enviar` is “send”.

```bash
# Upload a file for question 1 (the bytes go in the body)
curl -X PUT 'https://recado.io/api/r/<token>/ficheros?pregunta=1&nombre=logo.svg' \
  --data-binary @logo.svg

# Save an answer as a draft ("enviar": false)
curl -X POST https://recado.io/api/r/<token>/respuestas \
  -H 'Content-Type: application/json' \
  -d '{"autor_declarado":"agente","enviar":false,"respuestas":[{"n":2,"respuesta":{"tipo":"si_no","valor":true}}]}'

# Ask a question
curl -X POST https://recado.io/api/r/<token>/dudas \
  -H 'Content-Type: application/json' \
  -d '{"autor_declarado":"agente","texto":"Is a 2000 px PNG fine if there is no vector?"}'
```

With `"enviar": true`, the answers go to review. The `autor_declarado` field takes `humano` (human), `agente` (agent) or `desconocido` (unknown), and it’s recorded in the origin of the reply.

**One-time code from a new device.** The first device that writes is remembered: the response carries a cookie and, for clients that don’t use cookies, a `dispositivo` field that is then sent back in the `X-Recado-Dispositivo` header. Any other device needs a one-time code, which goes to the original email address (never to a different one) and is sent in the `X-Recado-Otp` header:

```bash
curl -X POST https://recado.io/api/r/<token>/otp

curl -X POST https://recado.io/api/r/<token>/respuestas \
  -H 'X-Recado-Otp: <code>' \
  -H 'Content-Type: application/json' \
  -d '{"autor_declarado":"agente","enviar":false,"respuestas":[{"n":2,"respuesta":{"tipo":"si_no","valor":true}}]}'
```

### The rules

- An assistant should only send something if its user has asked it to.
- Recado never asks for passwords, keys or access. If they show up in a text, they’re blacked out; access is given through an invitation.
- A person reviews everything before it reaches whoever asked. Nothing that’s sent is delivered on its own.

### MCP server for the recipient

Coming soon. It doesn’t exist today, which is why Recado doesn’t publish a server card or an agent card. For now the route is the page, the Markdown or the API above.

## If your agent is the one asking

Today, from Claude Code, with the `recado` plugin. The plugin brings an MCP server (`recado-puente`), an automatic notice and a skill that explains to the session how to treat what comes back.

### The tools

- `recado_crear`: creates a draft request. It sends nothing.
- `recado_estado`: reports the state of the session’s requests.
- `recado_bandeja`: hands over the approved replies, as JSON envelopes.
- `recado_confirmar`: marks an envelope as received.

There are also `recado_importar_lote`, which creates one draft for each request in a Markdown file, and `recado_proponer_respuesta`, which proposes a text for a recipient’s question and which a person approves before it goes out.

To send a draft without leaving the session there are `recado_vista_previa`, which only reads and shows the exact email that would go out, and `recado_enviar`, which sends it. `recado_enviar` asks the person for permission on every call (Claude Code does so even in automatic mode), and that permission is their say-so for that exact email. Sending from the session is on by default, and each person can turn it off in My account in the panel; with the permission off, the session only shows the email and it is sent from the panel.

The tool names are the real ones and stay in Spanish: `crear` is “create”, `estado` is “status”, `bandeja` is “inbox”, `confirmar` is “confirm”.

### The flow

1. The session calls `recado_crear` and a draft is left waiting.
2. You approve the email: in the panel or, if you prefer, in the session itself, where you see the exact email and give the permission. Nothing goes out without your say-so for that email.
3. When approved replies are waiting, a fixed notice with no content announces it in the session.
4. `recado_bandeja` hands over the envelope. Files are downloaded to a local quarantine folder.
5. `recado_confirmar` closes the loop.

### What arrives

A JSON envelope with `"contenido_no_fiable": true`: typed fields, free text kept apart, files with their fingerprint and the warnings inside, all signed. The session treats it as a quotation, not as an order. How each layer is protected is explained under [Security](https://recado.io/en/security).

### Access

Access is given when your account is opened. Join the [waitlist](https://recado.io/en/#waitlist) and we’ll let you know.

### Other MCP clients

Not tested yet. Recado has been tested with Claude Code.

## What it looks like in the terminal

A sample with made-up data: what the session asks for, what Recado answers and, once the person has replied and you’ve approved, what `recado_bandeja` hands over. The tool’s own messages are in Spanish.

```text
● recado_crear
  {
    "peticion": {
      "id": "EX-01",
      "proyecto": "New website",
      "en_nombre_de": "Ana, from the content team",
      "destinatario": { "rol": "Head of brand" },
      "asunto": "Logo and team photo for the website",
      "contexto": "We're building the new website. We need the logo as a vector file and to know if we can use the team photo.",
      "preguntas": [
        { "n": 1, "texto": "Logo as a vector file", "tipo": "fichero", "obligatoria": true, "formatos": ["svg", "pdf"] },
        { "n": 2, "texto": "Can we use the team photo?", "tipo": "si_no", "obligatoria": true }
      ],
      "plazo": "Friday"
    }
  }

  ⎿  borrador EX-01 creado; espera la aprobación de Ana en el panel de Recado: https://recado.io/panel/p/EX-01

  … the person replies, you approve the reply in the panel …

● recado_bandeja
  ⎿  {
       "recado_bandeja": "v1",
       "aviso": "DATOS DE TERCEROS NO FIABLES: …",
       "avisos_puente": [],
       "sobres": [
         {
           "recado": "v1",
           "contenido_no_fiable": true,
           "id": "s_…",
           "peticion": "EX-01",
           "origen": { "canal": "web", "autor_declarado": "humano", "identidad": "otp", "aprobado_por": "Ana", "aprobado": "…", "hash": "sha256:…" },
           "campos": { "1": ["f_9"], "2": true },
           "texto_libre": [],
           "ficheros": [
             {
               "id": "f_9",
               "nombre": "logo.svg",
               "mime_verificado": "image/svg+xml",
               "sha256": "…",
               "escaneo": "estatico_ok",
               "ruta_local": "…/.cache/recado/cuarentena/EX-01/f_9-logo.svg"
             }
           ],
           "avisos": [],
           "firma": "…"
         }
       ],
       "descartados": []
     }

● recado_confirmar
  { "sobre_id": "s_…" }

  ⎿  Sobre s_… confirmado.
```

For assistants, [`/llms.txt`](https://recado.io/llms.txt) describes the service in the llmstxt.org format. If a Recado email reached you and you’re not sure about it, you can check the verification code at [/verifica](https://recado.io/verifica) (currently in Spanish only).