# Mail, channels and the delivery log (Comms)

Every mail and every outgoing webhook of ConnectCloud goes through one module, **comms**: it renders the message,
picks the channel, sends, retries and logs every delivery. Comms also receives mail – for tickets, recruiting and the
Belegeingang (inbound invoices) – and incoming webhooks. Everything below is under `https://api.mbcom.cloud/api/comms/v1`; every
operation is in the [Comms reference](/reference/comms).

| What | Operations | Permission |
|---|---|---|
| Channels | [`getBootstrap`](/reference/comms/getBootstrap), [`listChannels`](/reference/comms/listChannels), [`createChannel`](/reference/comms/createChannel), [`updateChannel`](/reference/comms/updateChannel), [`testChannel`](/reference/comms/testChannel), [`setSettings`](/reference/comms/setSettings) | read: `comms:read`, changes: `comms:admin` |
| Delivery log | [`listDeliveries`](/reference/comms/listDeliveries), [`getDelivery`](/reference/comms/getDelivery), [`retryDelivery`](/reference/comms/retryDelivery), [`cancelDelivery`](/reference/comms/cancelDelivery) | read: `comms:read`, retry and cancel: `comms:admin` |
| Receiving mail | [`listMailboxes`](/reference/comms/listMailboxes), [`createMailbox`](/reference/comms/createMailbox), [`getMailIntake`](/reference/comms/getMailIntake), [`setMailIntake`](/reference/comms/setMailIntake), [`listMailIntakeMails`](/reference/comms/listMailIntakeMails), [`reimportMailboxMail`](/reference/comms/reimportMailboxMail) | `comms:read` / `comms:admin` |
| Incoming webhooks | see [Webhooks](/guides/webhooks#incoming-webhooks) | `comms:admin` |

## How mail is sent – and what you can call

There is **no public route that sends an arbitrary mail**. Modules hand comms a template with parameters, never
finished HTML, and comms decides channel and layout; that interface is internal. As an API client you send mail
through the feature it belongs to, and comms delivers it:

| You want to | Call |
|---|---|
| Answer a desk ticket by mail | [`createItemMail`](/reference/desk/createItemMail) or a public comment – see [Desk tickets](/guides/desk-tickets) |
| Mail an issued invoice with its XRechnung | [`issueInvoiceDraft`](/reference/trade/issueInvoiceDraft) with `send: true` – see [Trade](/guides/trade) |
| Mail a lead or a contact from the CRM | [`sendContactMail`](/reference/crm/sendContactMail) (takes an `Idempotency-Key`) |
| Tell people or a system when something happens | a [flow](/guides/flows) with a `mail` node (people, groups, roles, `channel:<id>` for webhook and Teams channels) |
| Push events to your own endpoint | a webhook channel addressed from a flow – see [Webhooks](/guides/webhooks) |

Whatever sends it, every recipient becomes one **delivery** in the tenant's delivery log below, so you can follow it
the same way.

## Channels

A channel is a configured way out: the tenant's Microsoft 365 connection (mail sent from the tenant's own mailboxes),
a webhook endpoint, or a Microsoft Teams channel. The platform's own mail (Amazon SES) needs no channel. The kinds
and the fields each one needs (configuration and secrets) come from [`GET /bootstrap`](/reference/comms/getBootstrap)
(`channelKinds[]`, each with its `medium` – `email`, `webhook`, `teams` – and `fields`) – build a setup form from it rather than hard-coding fields.

- [`createChannel`](/reference/comms/createChannel) with `kind`, `name`, `config` and `secrets` (at most 20 channels).
  Secrets are stored encrypted and never returned; `secrets` in an answer only says which ones are set. Sending a
  secret empty or as `********` on [`updateChannel`](/reference/comms/updateChannel) keeps the stored value.
- Changes carry the channel's `rev` (optimistic locking, **409** when it changed).
- [`testChannel`](/reference/comms/testChannel) checks the connection (`lastCheckOk`, `lastError`); a webhook test
  sends a `comms.test` event.
- The first e-mail channel becomes the tenant's **default**; [`setSettings`](/reference/comms/setSettings) changes
  `defaultEmailChannelId` (empty: the platform channel). Teams channels are created by comms itself when the Teams
  app is added to a team (`createChannel` refuses the kind).

Setting up a webhook channel step by step, the request you receive and verifying its signature are in
[Webhooks](/guides/webhooks).

## The delivery log

[`listDeliveries`](/reference/comms/listDeliveries) is the tenant's log of every mail, webhook and Teams message,
newest first (`limit` 1–200 and `offset`). Filter by `status` (comma separated), `channelId`, `origin` (`api` –
sent by a module or a flow –, `job`, `test`, `subscription`, `event_push`) and `q` (recipient or subject):

```bash
curl 'https://api.mbcom.cloud/api/comms/v1/deliveries?status=dead,retry&limit=50' -H "Authorization: Bearer $ACCESS_TOKEN"
```

| `status` | Meaning |
|---|---|
| `queued`, `sending` | waiting or being sent |
| `retry` | an attempt failed; `nextAttemptAt` says when the next one runs (exponential backoff) |
| `sent` | the provider accepted it; for mail `feedback` adds what SES reported later (`delivered`, `delay`, `bounced`, `complaint`) |
| `dead` | every attempt failed (`lastErrorCode`, `lastError`) |
| `suppressed` | not sent on purpose, e.g. a bounced address or a person who switched the mail off |
| `expired`, `cancelled` | too late to send, or cancelled |
| `held`, `bundled` | waits for the recipient's digest or the end of an absence, or went out in a digest |

[`getDelivery`](/reference/comms/getDelivery) adds the `attemptLog`. Fix the cause of a `dead` delivery (a wrong
webhook URL, an expired Microsoft 365 secret) and queue it again with
[`retryDelivery`](/reference/comms/retryDelivery) – possible while its message still has its content and has not
expired, otherwise **409**. [`cancelDelivery`](/reference/comms/cancelDelivery) stops one that is still waiting. A
bounce or complaint suppresses the address for later mail as well.

## Receiving mail

Comms reads mail for three consumers: the **Belegeingang** (`invoice`: PDF and XML attachments go to the
[DMS](/guides/dms) and on to trade's [inbound invoices](/guides/trade#inbound-e-invoices)), **desk** (tickets) and
**recruiting**. [`listMailboxes`](/reference/comms/listMailboxes) (`?consumer=`) lists them, each either a platform
address (`kind` `ses`, `<local part>@<subdomain>.<mail domain>`) or a Microsoft 365 mailbox (`msgraph`, read with a
Microsoft 365 channel). Platform addresses need the tenant's subdomain (set in the HR settings; until then
`mailDomain` is empty and creating one answers `400` with field `subdomain`).

The Belegeingang's platform address is managed on its own: [`getMailIntake`](/reference/comms/getMailIntake) shows
it, [`setMailIntake`](/reference/comms/setMailIntake) activates it (`rev: 0`; a random suffix is added by default so
the address cannot be guessed), and [`rotateMailIntake`](/reference/comms/rotateMailIntake) replaces it – the old one is
still accepted for `graceDays` (14 by default, `0` when it leaked). Suppliers then mail their invoices to that
address.

[`listMailIntakeMails`](/reference/comms/listMailIntakeMails) and [`listMailboxMails`](/reference/comms/listMailboxMails)
list what came in with its `state` (`PENDING` waits for the consumer, `COMPLETED`, `REJECTED`, `DEAD_LETTER`, …) and
`lastError`; [`reimportMailboxMail`](/reference/comms/reimportMailboxMail) imports one again (`202`).

## Webhooks in short

- **Outgoing:** a webhook channel plus a flow that addresses it; requests are signed per Standard Webhooks, retried
  and logged like every delivery – [Webhooks](/guides/webhooks).
- **Incoming:** [`createInboundHook`](/reference/comms/createInboundHook) gives a URL other systems post to without a
  ConnectCloud token (verified by signature, stored, readable with
  [`listInboundHookEvents`](/reference/comms/listInboundHookEvents)); to start an automation from a call, use a flow's
  webhook trigger instead – [Flows](/guides/flows).
