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.
| What | Operations | Permission |
|---|---|---|
| Channels | getBootstrap, listChannels, createChannel, updateChannel, testChannel, setSettings |
read: comms:read, changes: comms:admin |
| Delivery log | listDeliveries, getDelivery, retryDelivery, cancelDelivery |
read: comms:read, retry and cancel: comms:admin |
| Receiving mail | listMailboxes, createMailbox, getMailIntake, setMailIntake, listMailIntakeMails, reimportMailboxMail |
comms:read / comms:admin |
| Incoming webhooks | see 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 or a public comment – see Desk tickets |
| Mail an issued invoice with its XRechnung | issueInvoiceDraft with send: true – see Trade |
| Mail a lead or a contact from the CRM | sendContactMail (takes an Idempotency-Key) |
| Tell people or a system when something happens | a flow 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 |
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
(channelKinds[], each with its medium – email, webhook, teams – and fields) – build a setup form from it rather than hard-coding fields.
createChannelwithkind,name,configandsecrets(at most 20 channels). Secrets are stored encrypted and never returned;secretsin an answer only says which ones are set. Sending a secret empty or as********onupdateChannelkeeps the stored value.- Changes carry the channel's
rev(optimistic locking, 409 when it changed). testChannelchecks the connection (lastCheckOk,lastError); a webhook test sends acomms.testevent.- The first e-mail channel becomes the tenant's default;
setSettingschangesdefaultEmailChannelId(empty: the platform channel). Teams channels are created by comms itself when the Teams app is added to a team (createChannelrefuses the kind).
Setting up a webhook channel step by step, the request you receive and verifying its signature are in Webhooks.
The delivery log
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):
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 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 – possible while its message still has its content and has not
expired, otherwise 409. 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 and on to trade's inbound invoices), desk (tickets) and
recruiting. 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 shows
it, setMailIntake activates it (rev: 0; a random suffix is added by default so
the address cannot be guessed), and 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 and listMailboxMails
list what came in with its state (PENDING waits for the consumer, COMPLETED, REJECTED, DEAD_LETTER, …) and
lastError; 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.
- Incoming:
createInboundHookgives a URL other systems post to without a ConnectCloud token (verified by signature, stored, readable withlistInboundHookEvents); to start an automation from a call, use a flow's webhook trigger instead – Flows.