# Mailbox detection (https://docs.walido.it/docs/public/mailbox-detection)

Mailbox detection tells you whether an outbound call reached a person or a
machine. Turn it on per call, then read the result from
[getCall](/docs/public/calls/getCall). This guide shows how a workflow tool
such as n8n can use it to work through a lead list. Walido places each call; the
retry schedule is yours.

## Start a call with detection [#start-a-call-with-detection]

Detection is off unless you set `mailbox_detection: true`:

```bash
curl -X POST https://api.walido.it/api/v1/calls \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "assistant_id": "<assistant_id>", "to": "+491701234999", "mailbox_detection": true }'
```

Detection works for assistants whose `language` is `de`. For any other
language, including `de-CH`, the call runs normally and detection reports
`skipped` with the reason `language_not_supported`.

## Read the result [#read-the-result]

Poll the call until `done` is `true`. The result is in `mailbox_detection`;
`connection` tells how the attempt ended at the telephone network:

```json
{
  "data": {
    "id": "65f8fa6f1a9d8e0012ab34cd",
    "done": true,
    "ended_at": "2026-07-01T10:00:00.000Z",
    "connection": {
      "status": "answered",
      "answered_at": "2026-07-01T09:59:42.000Z",
      "sip_status": 200
    },
    "mailbox_detection": {
      "status": "completed",
      "category": "machine-vm",
      "reason": "Voicemail instructions permit leaving a message.",
      "greeting": "Bitte hinterlassen Sie eine Nachricht nach dem Signalton.",
      "decided_at_ms": 10400
    }
  }
}
```

A machine category (`machine-vm`, `machine-ivr`, `machine-unavailable`) ends
the call. `human` and `uncertain` leave the conversation running. See
[getCall](/docs/public/calls/getCall) for every field.

Detection only runs on a call that was accepted. A call that nobody accepted,
or that met a busy line, reports `connection.status` `no_answer` or `busy`, and
its detection is `skipped`. An accepted call that ended before the verdict
reports `skipped` too, so read `connection` first. Every ended outbound call
carries `connection`, with or without detection. `started_at`,
`duration_seconds`, an empty transcript and `success` do not tell whether a
call was answered.

Poll every 5 seconds for the first minute, then every 15 seconds. If a call
has no result after 30 minutes, mark the lead for review instead of calling
again.

## Keep an attempt ledger [#keep-an-attempt-ledger]

For each lead, store its ID, phone number, attempt count, current call ID,
processed call IDs, next attempt time, and status. Use a store with atomic
updates so one lead never has two active attempts, and so a repeated poll or
a restarted workflow never counts an attempt twice.

Reserve the attempt before you create the call, and save the returned call ID
right after. Set your own attempt limit and count attempts in total, not
retries. This guide uses three.

<Callout type="warn">
Creating a call is not idempotent. Turn off automatic retries on the request
that creates the call. If it times out or returns an unclear error, the call
may already exist: pause the lead and check before trying again.
</Callout>

## Decide once per ended call [#decide-once-per-ended-call]

| `connection.status` | Detection result | Action |
|---|---|---|
| `no_answer` or `busy` | any | Nobody was reached. Schedule the next attempt on your own schedule, or mark the lead exhausted at your attempt limit. |
| `answered` | `completed` with a machine category | Schedule the next attempt no earlier than the call's `ended_at` plus two hours, or mark the lead exhausted at your attempt limit. |
| `answered` | `completed` with `human` or `uncertain` | Use your qualification analysis (below). |
| `answered` | `failed`, `skipped`, or missing | Mark the lead for review. |
| Any other value, or `connection` missing | any | Mark the lead for review. |

The other two values are no proof that nobody was reached. `failed` covers
declined calls and numbers the network could not reach; `sip_status` carries
the code if you want to sort them. `"status": "unknown"` means the call ended
without a recorded telephony result. Carriers signal a manually declined call
differently: as `busy`, as `failed`, or by diverting it to voicemail, which
reads as `answered` with a machine category.

Schedule in UTC. Example: a machine answer ending at 10:00 UTC allows the next
attempt from 12:00 UTC.

Space calls from the same assistant at least 60 seconds apart. By default each
API key can create 60 calls per hour and make 1,000 reads per minute; see
[Errors & Rate Limits](/docs/errors).

## Qualification is a separate result [#qualification-is-a-separate-result]

Analyses, CRM actions, and notifications run for every call, including
machine calls, so check the detection result before acting on them. An ended
call can still have an analysis running: wait for your qualification
analysis to complete, and send failed or missing results to review. On a
transferred call, an analysis that uses `didTryForwarding` or
`didForwardingSucceed` starts only once the transfer has ended, at most 43
minutes later; allow for that before you treat its result as missing. The
call's `success` field says whether anything was left open after the call, not
whether the lead qualified.

Test the workflow with a few controlled leads before a real campaign,
including duplicate runs, restarts, and unclear responses.
