> For an agent: the map of this documentation is at https://escouade.io/en/mail/docs/llms.txt; every page exists in Markdown, at the same address with `.md` appended.

# Calendar and contacts

> Every inbox has a calendar and an address book. A phone shows them with an app password: one per device, created by the space's human, removed in one gesture. It does not send e-mail: sending always goes through Escouade Mail.

## What an app password opens

| Access | What it opens | For |
|---|---|---|
| `calendar_contacts` | The inbox's calendar (CalDAV) and contacts (CardDAV), with meeting requests: a meeting created with attendees goes out to them by e-mail, from the inbox's address, and their answers come back into the calendar. | A phone, a calendar app. |
| `mail_read` | Reading the inbox over IMAP: its folders and messages. Nothing is written, moved or deleted there. | Escouade, or an app that only reads. |

- **Neither sends e-mail.** A message sent from a phone would escape the sending window, the quotas, the warm-up, the block list and approval: sending goes through `send_email` and `reply_to_thread`.
- **The inbox's own password is never given out.** Each device has its own; removing one does not touch the others.
- **It is shown only once**, at creation. Escouade Mail does not keep it: if it is lost, create another one and remove the old one.
- **The space's human is told by e-mail** of every creation. Ten passwords at most per inbox, twenty creations at most per space per day.

## Getting the password

This is a gesture for the space's human: it needs the `approve` permission. An agent does not give itself an inbox's calendar.

- **In the workbench**, in their assistant or on the web page: Inboxes, the inbox, “Agenda, contacts et lecture” (calendar, contacts and reading), then “Brancher un téléphone ou un logiciel” (connect a phone or an app). The password is shown once, with the server and the username to enter.
- **By asking their assistant**, for example: “Connect my iPhone to the calendar of contact@example.com.” The assistant calls `create_app_password`.

What you enter on the device:

| Field | Value |
|---|---|
| Server | `mx1.subagent.fr` |
| Username | The inbox's address, for example `contact@example.com` |
| Password | The app password |

## iPhone and iPad

1. Settings › Apps › Calendar › Calendar Accounts › Add Account › Other › **Add CalDAV Account**. Before iOS 18: Settings › Calendar › Accounts.
2. Server `mx1.subagent.fr`, the inbox's address as the username, the app password, and a description (the inbox's name, for example). Next.
3. Contacts: Settings › Apps › Contacts › Contacts Accounts › Add Account › Other › **Add CardDAV Account**, with the same values.

The inbox's calendar appears in Calendar, its address book in Contacts. A meeting created on the phone in this calendar is saved in the inbox, and the other way round.

## Android

Android has no built-in CalDAV account: use the **DAVx⁵** app, on Google Play or F-Droid.

1. In DAVx⁵: add an account, **Login with URL and user name**.
2. Base URL `https://mx1.subagent.fr`, the inbox's address as the username, the app password.
3. Tick the calendar and the address book to synchronise. They appear in the phone's calendar and contacts.

## On a computer

Calendar and Contacts on a Mac, Thunderbird and other calendar apps: a CalDAV account and a CardDAV account, server `mx1.subagent.fr`, same credentials. An app that asks for the full address: `https://mx1.subagent.fr/.well-known/caldav` for the calendar, `https://mx1.subagent.fr/.well-known/carddav` for contacts.

## Meeting requests

- **A meeting with attendees**, created in the inbox's calendar, goes out to them by e-mail from the inbox's address: the meeting as an attachment (`.ics`) and a link to answer in one click, without a calendar. Their answers come back into the inbox's calendar.
- **Twenty attendees at most** per meeting. These e-mails are meeting requests, one per attendee, not a campaign: they do not count towards the inbox's daily quota.
- **A request received** arrives in the inbox as an e-mail, which Escouade Mail files in a thread. It adds itself to the calendar when its sender is authenticated (DMARC) and is in the inbox's contacts; otherwise, you accept it from the phone.

## Reading by Escouade

An inbox can be read in Escouade like its other mailboxes: its messages are attached to their correspondents' records.

1. In Escouade Mail: create an app password with the `mail_read` access (in the workbench: “Lecture de la boîte en IMAP (Escouade)”, reading the inbox over IMAP).
2. In Escouade: Settings › Accounts › **Escouade Mail inbox**, the inbox's address and this password. The Escouade space's “Escouade Mail inboxes” setting (Settings › Modules) must be switched on.

Escouade only reads: it marks nothing as read, moves nothing, sends nothing. The inbox's sends stay in Escouade Mail; Escouade sees what it receives. For another reading app: IMAP server `mx1.subagent.fr`, port 993, TLS.

## Your own domain

Nothing to publish: the device connects to `mx1.subagent.fr`. For an app to find the server from the inbox's address alone (DAVx⁵ signing in by e-mail address, a CalDAV account whose server is the domain), publish in the domain's DNS:

| Type | Name | Value |
|---|---|---|
| SRV | `_caldavs._tcp.example.com` | `0 1 443 mx1.subagent.fr.` |
| SRV | `_carddavs._tcp.example.com` | `0 1 443 mx1.subagent.fr.` |
| TXT | `_caldavs._tcp.example.com` | `path=/.well-known/caldav` |
| TXT | `_carddavs._tcp.example.com` | `path=/.well-known/carddav` |

They are recommended, not required: `verify_domain` does not check them.

## Removing a device

A lost phone, an app no longer in use: remove its password. The device can no longer connect; the calendar and contacts stay in the inbox. In the workbench: “Agenda, contacts et lecture”, the device, “Retirer” (remove). Through the tool: `revoke_app_password`.

Deleting the inbox with `delete_inbox` removes everything: its passwords, its calendar and its contacts.

## `create_app_password`

Creates an app password for an inbox. Permission: `approve`. The space must be verified.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `inbox_id` | text | yes | The inbox (`inb_…`, see `list_inboxes`). |
| `access` | text | no | `calendar_contacts` (the default): the calendar and contacts. `mail_read`: reading over IMAP. |
| `label` | text | no | The device's name, 2 to 60 characters, one line. Absent: “Téléphone” (phone), or “Escouade” for reading. |

The result carries `password` (this one time only), `username`, `server`, `caldav_url`, `carddav_url`, `imap` (`host`, `port`, `security`), `guide_url` and `app_password` (`id`, `label`, `access`, `created_at`).

Refusals specific to the tool: `app_passwords_unavailable` (the server has not opened it yet), `app_password_limit` (ten already on the inbox), `inbox_not_managed` (an inbox whose password Escouade Mail does not keep), `space_rate_limited`, `provisioning_failed`.

## `list_app_passwords`

Lists an inbox's app passwords: the device's name, the access, the creation date, never the secret. It also returns the server and the username to enter. Permission: `approve`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `inbox_id` | text | yes | The inbox (`inb_…`, see `list_inboxes`). |

## `revoke_app_password`

Removes an app password: the device using it can no longer connect. No going back. Permission: `approve`. A password already removed returns `already_revoked: true`, without changing anything.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `inbox_id` | text | yes | The inbox (`inb_…`, see `list_inboxes`). |
| `app_password_id` | text | yes | The password to remove, as `list_app_passwords` gives it. |
| `confirm` | boolean | yes | Must be `true`. |