> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visiqlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Email approvals

> Set the catch-all address that receives Human-in-the-Loop approvals for agents with no registered owner.

Email is the simplest connector VisIQ has: one address, no credential, about a minute of work. It is also the safety net that keeps an approval from going nowhere.

Configure it at **Connectors → Human-in-the-Loop → Email**.

***

## What this address is for

Email is your organisation's **catch-all**, not your only delivery path.

When you connect an agentic framework or tool, you choose that agent's approval pathway and register its owner. Approvals for an agent with an owner go straight to that person. This address is where an approval lands when the agent has **no owner registered** — so an admin can see what is running, decide it, and assign someone.

| Situation                                  | Where the approval goes                                                                                            |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| **Claimed agent** — an owner is registered | Directly to that owner, over the pathway chosen for the agent.                                                     |
| **Unclaimed agent** — no owner yet         | To this catch-all address, flagged with the agent's id and reported environment so you can attribute and claim it. |

The dashboard queue is always active regardless of what you configure here, so an approval is never lost because a channel is unset.

***

## Set it up

1. Open **Connectors → Human-in-the-Loop → Email**.
2. Enter the **catch-all address** — a shared mailbox such as `approvals@yourcompany.com` works well, because unclaimed-agent approvals are an admin task rather than one person's.
3. **Save.**

There is no API key, no webhook, and no credential of any kind: VisIQ sends these from its own outbound mail infrastructure. The connector is treated as configured as soon as it holds a non-empty address, which is why the card flips to **Connected** immediately after saving.

Once saved, **Send test** delivers a real approval-shaped email to the address so you can confirm it arrives and is not caught by a spam filter or a mailbox rule.

***

## What the email contains

Each approval email renders, in order: a branded header, the rule or policy reason that routed the call to approval, an AI-generated risk summary, an action-details table, and the call-to-action links. For an unclaimed agent the message also names the agent id and the host it reported from, which is the information you need to assign an owner.

| Link                 | What happens                                                                                                                        |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Approve**          | The tool call runs with its full arguments.                                                                                         |
| **Deny**             | The tool never runs; the agent receives the standard block message as the tool's output.                                            |
| **Investigate**      | Opens the pending item in the VisIQ dashboard — an auth-gated, read-only deep link that takes no governance action. Always present. |
| **Let VisIQ decide** | Hands the pending item to VisIQ's automated reviewer. Shown only when that is available for the agent.                              |

The links carry signed, single-use, expiring tokens. Clicking one after somebody else has already resolved the item is safe — the decision is not applied twice.

***

## The API behind the card

Both endpoints require a session and the `connectors:manage` permission.

| Method   | Path                                       | Body                                   | Purpose                                          |
| -------- | ------------------------------------------ | -------------------------------------- | ------------------------------------------------ |
| `PUT`    | `/api/connectors/hitl-channels/email`      | `{ enabled?, display_label?, config }` | Create or update the connector.                  |
| `DELETE` | `/api/connectors/hitl-channels/email`      | —                                      | Remove the connector.                            |
| `POST`   | `/api/connectors/hitl-channels/email/test` | —                                      | Send a test message through the saved connector. |

Unlike Slack, `config` is **required** on an email upsert, and it holds exactly one field:

```json PUT /api/connectors/hitl-channels/email theme={null}
{
  "enabled": true,
  "display_label": "Approvals mailbox",
  "config": {
    "address": "approvals@yourcompany.com"
  }
}
```

The body is validated strictly: `address` must be a valid email address, and any key VisIQ does not recognise is rejected rather than ignored. `display_label` is capped at 120 characters.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="The card says Connected but nothing arrives">
    Email is marked connected as soon as a valid address is stored — that is a statement about configuration, not about deliverability. Use **Send test** to prove delivery end to end, then check the mailbox's spam folder and any routing rules on a shared mailbox.
  </Accordion>

  <Accordion title="Approvals are going to an owner instead of this address">
    That is the intended behaviour for an agent that has an owner registered. This address only receives approvals for agents nobody owns yet. To change where a specific agent's approvals go, set its owner and pathway on the Agents page.
  </Accordion>

  <Accordion title="An approval expired before anyone opened the email">
    The approval window is capped at 120 seconds and an unanswered request fails closed, so email suits review-after-the-fact and low-volume gates better than time-critical ones. For interactive, in-the-moment approvals use [Slack](/connectors/slack).
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Slack approvals" icon="slack" href="/connectors/slack">
    Interactive Approve and Deny buttons in a channel, with owner direct messages.
  </Card>

  <Card title="Human-in-the-Loop" icon="user-check" href="/rules/action/hitl">
    How approvals pause a tool call, owner routing, and the timeout model.
  </Card>
</CardGroup>