# REST-API: was das Büro verlässt

Adresse: https://docs.athaus.ai/api/v1/hinausgehen

> Anfragenden antworten und nachfassen. Wann eine Nachricht sofort hinausgeht, wann ein Vorschlag auf ein Ja wartet (202) und wie du das Ergebnis liest.

Typ: Anleitung
Zuletzt aktualisiert: 2026-11-16

Manche Operationen erreichen eine Person außerhalb des Büros. Heute gibt es drei, zwei bei einer Anfrage und eine beim Inserat:

| Pfad                                            | Was geschieht                                                                                                               |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/inquiries/{id}/messages`              | eine Antwort an die Person, die angefragt hat                                                                               |
| `POST /v1/inquiries/{id}/followUps`             | ein Nachfassen; ohne `text` mit dem Standardtext von Athaus                                                                 |
| `POST /v1/listings/{externalListingId}/publish` | das Inserat geht online; Antwort `200` mit dem Inserat oder `202` mit einem Vorschlag ([Inserate](/api/v1/inserate#status)) |

Eine E-Mail lässt sich nicht zurückholen. Darum entscheidet dein Key allein nicht, ob sie hinausgeht.

## Hinausgehen oder warten [#hinausgehen-oder-warten]

Die Regel ist dieselbe wie beim MCP-Werkzeug `draft_reply`. Eine Nachricht geht nur dann sofort hinaus, wenn beides gilt:

1. Der Key hat den Scope `approve`.
2. Das Büro hat diese Art Nachricht in der App unter Automatik auf "Automatisch" gestellt.

| Key           | Büro        | Antwort                             |
| ------------- | ----------- | ----------------------------------- |
| `approve`     | Automatisch | `201`, die Nachricht ist eingereiht |
| `approve`     | Erst fragen | `202`, ein Vorschlag wartet         |
| nur `propose` | beliebig    | `202`, ein Vorschlag wartet         |
| nur `read`    | beliebig    | `403`, `insufficient_permissions`   |
| beliebig      | Aus         | `409`, `automation_disabled`        |

Auch `201` heißt nicht "zugestellt". Die E-Mail steht in der Warteschlange; zugestellt ist sie, sobald der Vorschlag `executed` zeigt.

Der Key braucht außerdem die Stufe `write` auf `inquiries`.

## Die Stufe lesen [#die-stufe-lesen]

`GET /v1/automations` nennt für jede Art von Aktion die Stufe des Büros: `off`, `ask` oder `auto`. `GET /v1/automations/reply` liefert die Stufe für Antworten, `follow_up` die für das Nachfassen. Lies sie vor dem Senden, wenn du wissen willst, ob eine Nachricht mit `201` oder `202` antwortet. Setzen kannst du eine Stufe über die API nicht: Das tut in der App, wer das Büro verwaltet. Ein Test-Key sieht die Stufen seines Testbüros. Der Key braucht die Stufe `read` auf `inquiries`.

## Der Kopf Idempotency-Key ist Pflicht [#der-kopf-idempotency-key-ist-pflicht]

Ohne ihn antwortet die API `400` mit `idempotency_key_missing`, und nichts läuft. Schicke je Nachricht eine neue UUID und nutze sie nur wieder, um genau diese Anfrage zu wiederholen.

Eine Wiederholung bekommt dieselbe Antwort mit `Idempotent-Replayed: true`, auch eine `202`, mit demselben Vorschlag. Ein zweiter entsteht nie. Die gespeicherte Antwort zeigt den Stand des ersten Aufrufs: Den heutigen liest du unter `GET /v1/proposals/{id}`. Die übrigen Regeln stehen unter [Schreiben](/api/v1/schreiben#wiederholen-ohne-doppelt-zu-schreiben).

## Die 202 und der Vorschlag [#die-202-und-der-vorschlag]

```bash
curl -X POST https://api.athaus.ai/v1/inquiries/0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17/messages \
  -H "Authorization: Bearer ath_live_..." \
  -H "Idempotency-Key: 6f1d9a4e-2b0c-4d7e-8a35-91c7e2f0b8d3" \
  -H "Content-Type: application/json" \
  -d '{"text":"Guten Tag, die Wohnung ist noch verfügbar. Gern zeige ich sie Ihnen diese Woche."}'
```

```http
HTTP/1.1 202 Accepted
Location: /v1/proposals/0190f3b8-5a21-7c34-9e10-4d8a6b2c7f15
```

```json
{
  "object": "proposal",
  "id": "0190f3b8-5a21-7c34-9e10-4d8a6b2c7f15",
  "status": "pending",
  "action": "inquiry.reply",
  "target": { "object": "inquiry", "id": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17" },
  "text": "Guten Tag, die Wohnung ist noch verfügbar. Gern zeige ich sie Ihnen diese Woche.",
  "livemode": true,
  "createdAt": "2026-11-12T09:14:03Z",
  "decidedAt": null,
  "decidedBy": null,
  "executedAt": null
}
```

Es ist nichts hinausgegangen. Eine Person im Büro sieht den Vorschlag in der App und sagt Ja oder Nein. Über die API entscheidet nur ein Key mit dem Scope `decide` ([Ohne Person entscheiden](#decide)).

Bei `publish` ist `action` `listing.publish` und `target` das Inserat (`listingId`); `executedAt` ist gesetzt, sobald es online ist.

Die Liste der Werte von `action` ist offen: Es kommen neue dazu, ohne dass das ein Bruch ist. Behandle einen unbekannten Wert als Vorschlag, den du nur über `status` verfolgst.

## Zustände [#zustände]

`GET /v1/proposals/{id}` liefert den Vorschlag, `GET /v1/proposals` die Liste (Cursor wie überall, Filter `status`, Sortierung `createdAt`). Ein Key sieht nur die Vorschläge, die er selbst angelegt hat. Der Vorschlag eines anderen ist `404`.

| `status`   | Bedeutung                                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `pending`  | wartet auf ein Ja oder Nein                                                                                                    |
| `approved` | Ja gesagt, die E-Mail steht in der Warteschlange, noch nicht zugestellt                                                        |
| `executed` | zugestellt (`executedAt` ist gesetzt)                                                                                          |
| `failed`   | Ja gesagt, aber die Zustellung gab nach allen Wiederholungen auf                                                               |
| `rejected` | eine Person hat Nein gesagt                                                                                                    |
| `expired`  | verfallen: ein neuerer Vorschlag derselben Art zur selben Anfrage hat ihn ersetzt, oder das Büro hat die Sache selbst erledigt |

Es gibt keine Frist. Ein Vorschlag wartet, bis jemand entscheidet oder er verfällt. Frag nicht jede Sekunde ab: Ein Aufruf alle paar Minuten reicht.

`text` ist die Nachricht, wie sie hinausgeht. Hat eine Person sie vor dem Ja geändert, steht dort der geänderte Text.

## Was die API ablehnt [#was-die-api-ablehnt]

| Status | Code                                                             | Ursache                                                                                                                       |
| ------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `400`  | [`idempotency_key_missing`](/api/errors#idempotency_key_missing) | der Kopf fehlt                                                                                                                |
| `400`  | [`invalid_body`](/api/errors#invalid_body)                       | ein unbekanntes Feld, ein leerer Text, oder der Text behauptet etwas, das nicht am Inserat steht (`errors[].name` ist `text`) |
| `404`  | [`not_found`](/api/errors#not_found)                             | keine solche Anfrage in diesem Büro                                                                                           |
| `409`  | [`address_missing`](/api/errors#address_missing)                 | die Person ist über Athaus nicht erreichbar: kein Konto und keine E-Mail-Adresse                                              |
| `409`  | [`automation_disabled`](/api/errors#automation_disabled)         | das Büro hat diese Art Nachricht ausgeschaltet; es wird nichts vorbereitet                                                    |

Der Text wird gegen die Fakten am Inserat geprüft, bevor etwas entsteht. Ein Key ist keine Quelle von Fakten: Was nicht am Inserat steht, schreibt die API nicht in eine E-Mail. Besichtigungen absagen oder verschieben und ein Inserat löschen, das Besichtigungen hat, gibt es bei `/v1` noch nicht.

## Ohne Person entscheiden [#decide]

Standardmäßig sagt eine Person Ja. Das Büro kann einem Key das Recht geben, es selbst zu tun: den Scope `decide`. Dann gibt `POST /v1/proposals/{id}/approve` den Vorschlag frei und `POST /v1/proposals/{id}/reject` verwirft ihn, ohne dass jemand die Nachricht vorher liest.

**Das Risiko trägt das Büro.** Mails an Kunden und Anfragende gehen hinaus, ohne dass eine Person sie gesehen hat, und eine E-Mail lässt sich nicht zurückholen. Gib `decide` nur einem Key, dessen Texte du vertraust.

Wie es gilt:

* `decide` setzt `approve` und Schreibzugriff auf `inquiries` voraus. Ihn schaltet nur die Leitung des Büros beim Anlegen des Keys ein, in der App unter Einstellungen, API-Keys, mit einer Bestätigung. Kein bestehender Key hat ihn, auch keiner mit `approve`. `GET /v1/me` nennt ihn unter `key.scopes`.
* Ohne `decide` antwortet der Aufruf mit `403` [`insufficient_permissions`](/api/errors#insufficient_permissions).
* Ein Key entscheidet nur die Vorschläge, die er selbst angelegt hat, und nur Antworten und Nachfassen bei einer Anfrage. Alles andere ist `403` [`forbidden`](/api/errors#forbidden) oder, bei fremden Vorschlägen, `404`.
* Der Aufruf läuft durch denselben Code wie das Ja in der App: dieselben Prüfungen, dieselbe Frist, dieselbe Antwort `409` [`proposal_already_decided`](/api/errors#proposal_already_decided) bei einem entschiedenen oder verfallenen Vorschlag, dieselben Folgen. Mit einem `Idempotency-Key` ist ein Wiederholen sicher; ohne ihn ist die zweite Entscheidung ein `409`.
* Im Verlauf, am Vorschlag (`decidedBy`) und, wo die Nachricht im Haus in den Faden geschrieben wird, in der Nachricht steht der Key mit Name und Id, nicht die Person, die ihn angelegt hat. Geht die Mail aus einem Postfach, steht der Key am Vorschlag und im Verlauf, und der Faden zeigt die Mail des Postfachs.
* Höchstens 30 Entscheidungen je Minute und Key, mit einem Stoß von 10 ([Grenzen](/api/v1/limits)). Die Grenzen dessen, was ein Ja auslöst, gelten weiter.
* Eine Anfrage von außerhalb ohne Faden in einem Postfach des Büros hat keinen Weg für die Mail: `409` [`mailbox_not_connected`](/api/errors#mailbox_not_connected), der Vorschlag bleibt offen. Ein Key hat kein eigenes Postfach, das als Ausweg dient.
* Geht die Mail aus dem Postfach eines Mitglieds, weil dort der Faden der Anfrage liegt, geht sie von diesem Postfach ab, während am Vorschlag der Key steht.

## Im Testmodus [#im-testmodus]

Mit einem Test-Key geht nichts hinaus, auch nach einem Ja nicht. Du kannst den Vorschlag selbst entscheiden: `POST /v1/proposals/{id}/approve` oder `/reject`, ohne den Scope `decide`. Die Nachricht steht dann im Verlauf als gesendet, mit dem Vermerk, dass sie nicht zugestellt wurde ([Testmodus](/api/v1/testmodus)).

## Grenzen [#grenzen]

Diese Operationen nutzen den Eimer fürs Schreiben ([Grenzen](/api/v1/limits)). Eine gedrosselte Anfrage läuft nie.
