ConnectCloud Developers

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.

  • 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 keeps the stored value.
  • Changes carry the channel's rev (optimistic locking, 409 when it changed).
  • 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 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.

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: createInboundHook gives a URL other systems post to without a ConnectCloud token (verified by signature, stored, readable with listInboundHookEvents); to start an automation from a call, use a flow's webhook trigger instead – Flows.

View as Markdown