External integrations and communications
External integrations connect a workspace to outside accounts, services, and applications. They support account-based synchronization, messages, calendars, email, files, webhooks, installed application behavior, and delivery between a local application project and a remote Twenty workspace.
Connected accounts
Account ownership
A connected account represents an external identity that a workspace can use. The account belongs either to one workspace member or to the workspace. Its scope controls who may use it and which channels or application actions may access it.
Provider support covers Google, Microsoft, direct IMAP, SMTP, and CalDAV connections. Installed applications can add connection providers for their own external services. These providers identify an account, authorize it, and manage its connection lifecycle. Application providers expose either workspace or user scope so an application can state whether a connection is shared or personal.
References: packages/…/connected-account.entity.ts• L25-127 packages/…/connection-provider-connected-account.service.ts• L42-67 packages/…/connection-provider-lifecycle-hook.service.ts• L37-76 packages/…/application-connection-provider.dto.ts• L23-49 packages/…/connection-provider-scope.enum.ts• L5-12
Account authorization
Account authorization is a controlled handoff between the workspace, the provider, and the external service. The system checks the connection provider, workspace, member, and browser session before it starts. A short-lived signed state value binds the callback to the original workspace and account request.
OAuth providers can use PKCE. The state also carries the scope, reconnect target, and safe return location. After the provider returns a code, the system exchanges it for tokens, identifies the external account, and stores the account with encrypted credentials. A custom provider can receive either a browser callback or a server notification callback. An API-key provider follows the same account boundary without an OAuth callback. It verifies the key through the application's account-identification action before it saves the account. See Connected accounts and messaging for the account and provider flow.
OAuth discovery providers can learn the protected resource and authorization server before sign-in. They reuse a stored client when its discovery state is still valid. Otherwise, they use the provider's supported client identification path and store one client for the workspace.
References: packages/…/app-connection-access.service.ts• L17-57 packages/…/connection-provider-authorization-state.service.ts• L34-120 packages/…/connection-provider-oauth-flow.service.ts• L46-99 packages/…/connection-provider-oauth.controller.ts• L77-253 packages/…/connection-provider-custom.controller.ts• L45-137 packages/…/connection-provider-flow-redirect.service.ts• L40-83 packages/…/connection-provider-api-key-flow.service.ts• L33-98 packages/…/discovered-oauth-client.driver.ts• L67-117
Account credentials
The account keeps credentials, scopes, expiry, and authentication state separate from synced workspace data. Access tokens are reused until they approach expiry. Providers that support refresh renew the credentials and save the new token pair before the next external operation.
The system treats a temporary token endpoint or network failure as retryable. A provider rejection that shows an invalid refresh token moves the account toward reconnect instead of being treated as a transient outage. Direct protocol accounts and API-key accounts do not use OAuth token refresh.
References: packages/…/connected-account-refresh-tokens.service.ts• L51-84 packages/…/connected-account-refresh-tokens.service.ts• L145-225 packages/…/app-oauth-refresh-tokens.service.ts• L28-79 packages/…/connection-provider-api-key-flow.service.ts• L65-90
Application account access
Application account access exposes only the connected accounts that the application and the requesting member may use. A workspace-scoped account is available to the workspace. A member-scoped account is visible only to that member when a request has a member context.
The application can filter accounts by provider, member, and scope. The response refreshes usable credentials before it returns them and omits accounts whose provider is no longer available. This keeps application actions separate from a member's personal account access.
References: packages/…/application-connections-list.service.ts• L64-131 packages/…/application-connections-list.service.ts• L194-297
External channels
Message channels
A message channel is the workspace view of a message source on a connected account. It defines the source to sync, visibility, filters, and rules for turning external participants into workspace people or members.
Google, Microsoft, and IMAP channels import email. Email groups provide shared addresses, and application-owned channels can accept messages from an installed application instead of polling a provider. Folder links track where a message appears in the external source. The shared message path keeps external identities stable, avoids duplicate messages, and preserves thread, participant, and attachment links. Attachment content may remain with the provider until a user requests it.
Blocklists, group-email rules, upstream spam checks, and provider errors all affect whether a message enters the workspace. See Connected accounts and messaging for the message lifecycle.
References: packages/…/message-channel.entity.ts• L51-176 packages/…/messaging-save-messages-and-enqueue-contact-creation.service.ts• L75-137 packages/…/messaging-message-folder-association.service.ts• L16-93 packages/…/messaging-message-cleaner.service.ts• L29-141 packages/…/inbound-email-import.service.ts• L115-158
Calendar channels
A calendar channel is the workspace view of a calendar on a connected account. It carries the calendar identity, sync state, visibility, participant rules, and change-notice state.
Google Calendar, Microsoft Calendar, and CalDAV data are mapped to one workspace event model. Stable external identities support updates and removal. Provider-specific sharing rules can link the same meeting from more than one channel without allowing an attendee channel to replace organizer-owned data.
References: packages/…/calendar-channel.entity.ts• L39-134 packages/…/calendar-save-events.service.ts• L36-309 packages/…/resolve-calendar-event-sharing.util.ts• L13-92 packages/…/calendar-event-composer.service.ts• L46-82
Channel visibility
Channel visibility limits how much external data a member can see. Message channels can share full messages, subjects, or only metadata. Calendar channels can share full events or only calendar metadata.
The visibility decision uses the channel associations and the member's ownership of the connected account. Calendar fields such as the title and description are restricted when no associated channel grants full access. The same rule applies to list and single-record views.
References: packages/…/apply-messages-visibility-restrictions.service.ts• L31-182 packages/…/apply-calendar-events-visibility-restrictions.service.ts• L30-133
Synchronization
Sync pipeline
Synchronization turns provider records into workspace records while keeping the provider as the source for external state. Each channel tracks progress so discovery and import can continue in batches.
The common flow is:
- A provider notice, schedule, blocklist change, or user action marks a channel for work.
- Discovery finds changed external identities and advances the provider cursor.
- Import applies channel and workspace rules.
- Accepted records are saved with their links to channels, threads, people, members, events, or remote attachments.
- The channel records the next sync state or enters recovery.
This diagram shows how an external change becomes workspace data.
flowchart LR
A[External change] --> B[Channel sync request]
B --> C[Discover changed identities]
C --> D[Apply channel rules]
D --> E[Import workspace records]
E --> F[Save links and sync state]
Temporary failures wait for retry. Permission failures require account recovery. An invalid message cursor starts a new discovery pass so incremental sync does not silently miss records. A full message pass also removes channel links for records no longer present in the provider result.
References: packages/…/channel-sync.service.ts• L61-184 packages/…/gmail-get-history.service.ts• L15-63 packages/…/messaging-message-list-fetch.service.ts• L118-255 packages/…/messaging-message-cleaner.service.ts• L143-281 packages/…/message-channel-sync-status.service.ts• L59-239
Message synchronization
Message synchronization discovers folders and message identities before it imports message content. Provider history can report additions, deletions, and label changes. Folder links are then reconciled so workspace messages follow the source mailbox.
The import path filters spam, blocked senders, group-email rules, and channel handles before it saves a message. It saves message, thread, participant, folder, and attachment links through the shared message path. External message and header identities prevent duplicate workspace records across repeated syncs. Drafts that become sent are refreshed instead of becoming separate messages, and later matching work can repair links to people or members.
Attachment metadata is stored separately from attachment content. The system ignores mail-system files and inline images that do not represent user files. Eligible remote attachments keep their provider identity and are fetched from Gmail, Microsoft, or IMAP only when needed. This keeps message import light while still allowing the workspace to present the file later. Fetches are limited per connected account so repeated access does not overload the provider. The file service then serves a stored file or opens its remote content through the remote file source, without treating the remote file as local storage.
Message text is normalized without quoted history where the provider body marks a prior exchange. This keeps a new message focused on its current content while preserving the original message record for the thread.
References: packages/…/gmail-get-history.service.ts• L66-120 packages/…/messaging-message-list-fetch.service.ts• L107-255 packages/…/messaging-messages-import.service.ts• L103-227 packages/…/messaging-message.service.ts• L54-381 packages/…/messaging-save-messages-and-enqueue-contact-creation.service.ts• L75-293 packages/…/messaging-message-attachment.service.ts• L106-191 packages/…/messaging-remote-attachment.service.ts• L53-105 packages/…/filter-importable-message-attachments.util.ts• L7-27 packages/…/resolve-message-attachment-mime-type.util.ts• L8-29 packages/…/extract-imap-body-structure-attachments.util.ts• L10-54 packages/…/extract-microsoft-file-attachments.util.ts• L7-29 packages/…/get-attachment-data.util.ts• L9-54 packages/…/file.service.ts• L92-176
Calendar synchronization
Calendar synchronization separates event discovery from event import. Discovery records changed event identities. Import then normalizes provider data and reconciles event fields, channel links, cancellations, recurrence, and participants.
The save path can skip unchanged records and remove events that are canceled or no longer belong to the channel. Creation returns an external identity when possible, so a later sync can reconcile a provider-created event with its workspace record.
References: packages/…/calendar-events-import.service.ts• L51-211 packages/…/calendar-save-events.service.ts• L36-309 packages/…/caldav-create-event.service.ts• L25-115
Messaging and email
Email sending
Email sending uses a send-capable connected account and one of its verified aliases. The send flow supports new messages, replies, drafts, attachments, and sent-message persistence.
After delivery, the system saves the sent message through the shared message path. Provider message and thread identities are used when available. When a provider does not return them, the message header or parent thread keeps the send distinct and keeps replies in the right thread. Attachment storage is best effort, and temporary copies that are not linked to the saved message are removed. A cleanup failure after provider delivery does not claim that the email was unsent because later synchronization can repair local state.
A sent thread can also be linked to a workspace record when the caller has permission to update that record. This link uses the caller's record access and does not bypass it.
References: packages/…/send-email.service.ts• L21-103 packages/…/sent-message-persistence.service.ts• L38-177 packages/…/format-sent-message.util.ts• L13-65 packages/…/resolve-outbound-thread-external-id.util.ts• L5-29 packages/…/sent-message-record-link.service.ts• L19-77 packages/…/sent-message-persistence.service.spec.ts• L74-153
Campaign delivery
Campaign delivery sends a planned message to an audience through a verified workspace domain. A campaign can send now or at a future time. The delivery path recounts the audience near send time and applies suppression and plan rules before it queues recipients.
Campaign records preserve the sender, audience, content, topic, and schedule so the sent view remains useful after related workspace records change.
References: packages/…/message-campaign.service.ts• L1-200 packages/…/message-campaign-lifecycle.service.ts• L1-200 packages/…/message-campaign-audience.service.ts• L1-200 packages/…/email-group-message-outbound.service.ts• L49-153
Inbound email
Inbound email routes a message sent to a configured inbound address into an email-group channel. The route uses the envelope recipient and domain to select the channel, then imports the message through the normal message path.
Known message headers preserve the workspace thread. Unmatched recipients, unconfigured domains, and upstream spam messages do not create workspace messages. The source cleans up the inbound message after import or exclusion.
References: packages/…/inbound-email-import.service.ts• L45-158 packages/…/inbound-email-import.service.ts• L161-233 packages/…/is-upstream-spam.util.ts• L6-21
Email attachments
Email attachments use workspace file storage as a temporary handoff between the composer and the outbound send. The composer validates the file before upload and receives signed access without exposing the storage location.
Temporary files remain until the email flow uses or removes them. Cleanup continues when one file fails so a single stale attachment does not block the rest. Sent-message persistence also keeps the message when an individual attachment upload fails.
References: packages/…/file-email-attachment.service.ts• L23-89 packages/…/EmailComposerFields.tsx• L291-314 packages/…/sent-message-persistence.service.ts• L103-177 packages/…/file.service.ts• L217-276
Suppression controls
Suppression controls stop delivery to addresses that must not receive a message. Campaign and other bulk sends resolve suppression again at final handoff rather than trusting an earlier audience preview.
This last check protects the gap between audience selection and delivery. Unsubscribe topics and suppression records therefore affect the provider handoff, not only the user interface.
References: packages/…/message-suppression.resolver.ts• L46-93 packages/…/unsubscribe-topic.resolver.ts• L38-92 packages/…/emailing-domain-sender.service.ts• L89-209
Workflow communications
Workflows can use connected accounts to send or draft email and create calendar events. A record event, schedule, webhook, or manual run can therefore produce work in an external channel.
The workflow run records the selected account and action result. Application manifests can declare these account references, which are resolved during manifest validation before the workflow becomes workspace state. See Connected accounts and messaging for provider delivery rules.
References: packages/…/send-email.workflow-action.ts• L22-58 packages/…/create-calendar-event.workflow-action.ts• L19-52 packages/…/reconstruct-workflows-manifest.util.ts• L86-119
Webhook communications
Provider notifications
Provider notifications are inbound notices that keep message and calendar channels current. A valid notice schedules channel synchronization. It does not write provider data directly into workspace records.
Subscription state belongs to the channel. The system claims creation work to avoid competing watches, renews watches that are near expiry or stale, and revokes watches when a workspace is suspended or deleted.
References: packages/…/channel-sync.service.ts• L84-183 packages/…/messaging-webhook-subscription.service.ts• L42-368 packages/…/webhook-subscription-renewal.cron.job.ts• L68-140
Workspace event webhooks
Workspace event webhooks send selected workspace changes to an external URL outside the request that changed the workspace. They can match record events and metadata changes. A workspace role controls which records the webhook may include.
Webhook delivery is queued and rate limited before individual requests are sent. The payload describes the matching event in JSON. When configured with a secret, each request carries freshness data and an HMAC signature. Secure HTTP checks reject targets that resolve to private addresses. Delivery records keep the response and outcome for later inspection.
Workspaces can manage webhooks through GraphQL, REST, and application tools. Read, write, and delete operations use separate access policies. For application and extension behavior that uses these events, see Extension integrations.
References: packages/…/webhook.controller.ts• L36-105 packages/…/call-webhook-jobs.job.ts• L37-135 packages/…/create-webhook.tool.ts• L13-84 packages/…/webhook.resolver.ts• L31-89 packages/…/webhook-write-access-policy.constant.ts• L5-21 packages/…/webhook-read-access-policy.constant.ts• L5-18
Installed applications
Application catalog
An application registration is the shared identity for a package or OAuth-only client. It gives the catalog and installed workspaces a stable application identity, version, manifest, display data, and declared access.
The marketplace catalog exposes listed and built-in applications for discovery. Detail data shows the requested capabilities, roles, data objects, media permissions, billing, and support links before installation. This lets a workspace review the application's intended reach before it approves workspace state. See Packaged installed applications for the complete lifecycle.
References: packages/…/application-registration.service.ts• L905-1059 packages/…/marketplace-query.service.ts• L48-120 packages/…/marketplace-query.service.ts• L141-236 packages/…/marketplace-app-detail.dto.ts• L23-155
Application authorization
Application authorization records a member's consent for an application in a workspace. It stores the approved scope and use time, and it can be revoked for one member, one workspace, or one application without affecting unrelated grants.
An external OAuth client can discover an application's public identity and requested scopes before it starts consent. Authorization records the grant before tokens are issued. Revocation and later token use continue to check the client, grant owner, and current workspace access.
References: packages/…/application-authorization.service.ts• L16-57 packages/…/application-authorization.service.ts• L147-204 packages/…/oauth-client.resolver.ts• L35-92
Application installation
Installation turns a registration into workspace-scoped application state. The system checks server compatibility and access approval, stores the package, applies its manifest, and runs the declared lifecycle work.
Install, upgrade, and uninstall operations are serialized per workspace application. A fresh install can roll back partial state. An upgrade keeps the existing application when the new version fails. A package can contribute workspace data, user-interface parts, server actions, permissions, connection providers, messaging providers, workflows, and application variables. Local development applications are synchronized by the CLI, and OAuth-only applications have no code package to install.
Capability and embedded media access are limited to the approved set. Pre-install and post-install actions can prepare or finish workspace behavior. Uninstall removes application-owned workspace state and runtime resources, but it is blocked while another workspace depends on the shared application registration.
References: packages/…/application-install.service.ts• L102-168 packages/…/application-install.service.ts• L376-619 packages/…/application-uninstall-runner.service.ts• L36-117 packages/…/application-sync.service.ts• L340-494
Application manifests
An application manifest is the portable declaration of the workspace behavior and data that an application owns. Manifest synchronization validates references, compares the declaration with workspace state, and applies a migration that creates, updates, or removes the owned parts.
The model covers data objects and fields, views, layouts, navigation, roles, permissions, workflows, agents, skills, connection providers, messaging providers, related record paths, validation rules, and variables. It also maps application health checks and media permission requests to installed application state. Stable universal identifiers connect these parts across source, install, sync, export, and pull.
The sync can produce a dry-run plan before it changes the workspace. Removing a connection provider can also remove the connected accounts that depend on it, so the system validates the migration before it revokes those accounts and tokens. Translation updates and SDK client generation follow the resulting application state.
References: packages/…/application-sync.service.ts• L65-143 packages/…/application-manifest-migration.service.ts• L183-388 packages/…/application-manifest-apply.service.ts• L28-100 packages/…/application-manifest-migration.service.ts• L312-354
Application export
Application export rebuilds a portable manifest from application-owned workspace state. It also reports coverage for records that are exported, derived by the engine, owned by another application, unsupported, or excluded as runtime or workspace state.
Export can include dependency files, declared source files, and public assets. The CLI uses this export to pull a locally developed application. Packaged applications and the standard application are not treated as locally editable exports.
References: packages/…/application-development.service.ts• L104-123 packages/…/fetch-app-export.ts• L79-123 packages/…/fetch-app-export.ts• L174-202
Application configuration
Application variables hold workspace or user configuration for an installed application. Values are encrypted, secret values are masked in display views, and only workspace-scoped values become server environment values for application execution.
Required configuration takes priority over general health state. User variables stay separate from workspace variables and are resolved for the current member. See Extension integrations for the broader application extension model.
References: packages/…/application-variable.service.ts• L35-75 packages/…/application-variable.service.ts• L105-175 packages/…/user-application-variable-value.service.ts• L53-91
Application media permissions
Application media permissions control whether an embedded application may use a member's microphone or camera. The application manifest declares requested permissions for an origin. A workspace administrator reviews those requests and grants only permissions that the installed application requested.
The granted set is exposed separately from the requested set. If the request changes, the workspace must review it again before the new access can be granted.
References: packages/…/application-iframe-media-permission.resolver.ts• L50-113 packages/…/application-iframe-media-permission.service.ts• L31-107 packages/…/iframe-media-permission.input.ts• L5-18 packages/…/application.entity.ts• L141-146
Application health
Application health checks report whether an installed application can operate for a workspace or a member. A health check is an application-owned function that returns a small status and optional title, description, and user action.
The system returns unknown when the check fails or returns an invalid result. A per-member check runs only when the application enables it and is rate limited to protect both the workspace and the application. Configuration remains a separate prerequisite, so missing required settings can take priority over a healthy runtime result.
References: packages/…/application-health-check.service.ts• L20-157 packages/…/user-health-check-rate-limit.constant.ts• L1-2 packages/…/build-user-health-check-rate-limit-key.util.ts• L1-10 packages/…/application-manifest-migration.service.ts• L464-514
Application monitoring
Application monitoring gives an owner a time-bounded view of application runs, errors, rate limits, lifecycle events, versions, function activity, and credit use. An administrator can view the same registration across installed workspaces.
The period is limited by audit-log retention and uses larger time buckets for longer ranges. Ownership, workspace permissions, feature access, and application scope protect the result. Credit data can be unavailable without hiding the rest of the monitoring view.
References: packages/…/application-monitoring.service.ts• L66-121 packages/…/application-monitoring.service.ts• L124-158 packages/…/application-monitoring.service.ts• L161-254
CLI application delivery
Application source build
The application CLI turns local source into a validated manifest and a set of deployable files. It includes code reachable from declared application entries, preserves needed source and asset files, builds server and front-end parts, and records file identities for later synchronization.
The build rejects unsafe or missing local inputs and detects collisions between source files and generated files. This creates one package view that can support local development, remote synchronization, export, and publishing. See CLI application delivery for the developer workflow.
References: packages/…/manifest-build.ts• L95-186 packages/…/manifest-build.ts• L598-831 packages/…/manifest-validate.ts• L265-342 packages/…/build-application.ts• L56-219 packages/…/collect-application-source-files.ts• L12-149
Remote application delivery
Remote delivery sends a local application's manifest and files to one explicit Twenty target. The CLI can create or update the local application record, request a migration plan, show its changes, apply the plan, upload application files, publish a package, and generate a client from the remote API schema.
The plan separates creates, updates, deletes, and dependent deletes. Secret variable values remain hidden. Destructive changes are shown before apply, and missing source entities are pruned only when the selected mode allows it. File delivery uses server-issued upload targets and completes only the files that storage accepts.
This diagram shows the main remote delivery path.
flowchart LR
A[Local source] --> B[Build and validate manifest]
B --> C[Select remote target]
C --> D[Request migration plan]
D --> E[Review changes]
E --> F[Upload files]
F --> G[Apply manifest]
G --> H[Workspace application state]
Publishing a package registers it in the selected registry. Publishing does not install it in a workspace. Install remains a separate workspace action.
References: packages/…/format-app-plan.ts• L327-402 packages/…/group-app-plan-cascades.ts• L7-43 packages/…/parse-app-plan.ts• L47-77 packages/…/upload-app-files.ts• L322-385 packages/…/publish-app-to-server.ts• L18-143 packages/…/application-development.service.ts• L126-205
Application pull
Application pull brings an export from a remote custom application into a local project. It compares the remote manifest and files with a target-bound pull base, keeps local-only definitions where they are not replaced by workspace state, and writes only the planned changes.
The pull protects identifiers that the export still owns, tracks overwritten local changes, and records fingerprints for later pulls. It can restore declared front-end source, public assets, and dependency files, while rejecting unsupported or unsafe file paths. A report shows incomplete coverage, skipped entities, local-only files, and changes that replaced local edits.
References: packages/…/run-app-pull-command.ts• L42-107 packages/…/run-app-pull-command.ts• L148-246 packages/…/pull-application.ts• L32-227 packages/…/plan-public-asset-writes.ts• L11-68 packages/…/parse-pull-files.ts• L21-113
CLI target access
The CLI resolves a named remote or environment target before it makes a request. A target supplies the API URL and either an OAuth session or an API key. Expiring OAuth sessions can be renewed, and authenticating proxy headers can be loaded for that remote.
Transport keeps requests inside the selected target, does not follow redirects, limits response size, applies a timeout, and reports proxy, network, and authentication failures separately. This protects credentials and makes a failed delivery point to the target that needs attention.
References: packages/…/resolve-target.ts• L22-145 packages/…/create-target-fetch.ts• L116-202 packages/…/resolve-proxy-headers.ts• L1-200
Change checklist
When these files or sections are changed, remember to consider these:
- Keep account scope, application connection permissions, reconnect ownership, encrypted credentials, and channel access aligned.
- Keep OAuth token response parsing, expiry calculation, refresh timing, token rotation, API-key verification, and reconnect error mapping aligned for built-in and application providers.
- Keep OAuth state claims, one-time flow secrets, browser-session checks, callback methods, workspace-host redirects, and safe internal return paths aligned.
- Keep discovered resource metadata, authorization-server metadata, client identification, stored-client reuse, redirect URLs, and discovered scopes aligned.
- Keep provider normalization, stable external identities, channel roles, visibility rules, folder links, and orphan cleanup aligned across message and calendar sync.
- Keep discovery cursors, queued identities, import progress, retry state, provider history events, full-sync deletion, and provider notice handling aligned so a channel cannot silently skip or repeat data.
- Keep attachment metadata filtering, provider identities, remote file origins, lazy content fetch, MIME type fallback, and per-account fetch limits aligned across Gmail, Microsoft, and IMAP.
- Keep sender aliases, inbound domain routing, campaign suppression, audience recounts, threading headers, outbound fallback identities, and attachment cleanup aligned with provider delivery.
- Keep sent-thread record links behind the caller's record update permission and preserve the distinction between manual and automatic links.
- Keep manifest identifiers and references aligned across source build, install, sync, export, workflow account resolution, related record paths, validation rules, and application-owned data.
- Keep manifest coverage rules separate from runtime configuration, member assignments, workflow versions, health results, media grants, and other state that cannot be exported.
- Keep application registration versions, capability approval, media permission approval, lifecycle locks, rollback, uninstall blocking, and installed workspace state aligned.
- Keep requested and granted media permissions tied to the installed application's current manifest and origin.
- Keep health-check enablement, workspace and member scope, required configuration state, result validation, and per-user rate limits aligned.
- Keep workspace and user application variables separate, encrypted, masked, and excluded from reserved runtime names.
- Keep monitoring retention, period buckets, ownership scope, workspace filters, event sources, and credit usage mapping aligned.
- Keep webhook event matching, role-based record access, signing, target safety checks, queue retry, and rate limits aligned across GraphQL, REST, tools, and delivery jobs.
- Keep manifest validation, build outputs, file checksums, upload targets, destructive plan handling, remote selection, pull bases, public-asset paths, and generated clients aligned across CLI and server delivery.
- Keep package publishing separate from workspace installation, and preserve the distinction between local development apps, packaged apps, and OAuth-only clients.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| An application provider returns an invalid refresh token | Its connected account cannot access the external service | Treat provider 4xx token failures as reconnect state and keep transport or 5xx failures retryable |
| An API key is empty or account identification fails | The application cannot create a usable connected account | Trim and verify the key through the provider's identification action before saving it |
| OAuth callback state is missing, expired, consumed, or does not match the request | The account flow cannot complete or may be attached to the wrong workspace | Require signed state, one-time flow secrets, browser identity checks, and binding to the provider, workspace, member, and reconnect target |
| A custom callback omits the state query parameter | The provider cannot complete the account flow | Reject both browser and notification callbacks before forwarding the request |
| A discovered OAuth resource names another protected resource | Authorization can target an unintended service | Check that discovered resource metadata matches the configured resource |
| A reconnect identifies a different external account | Existing channel data can be attached to the wrong identity | Compare the identified external account before updating the reconnect target |
| A provider cursor becomes invalid | Incremental sync can miss external records | Reset discovery and run a full list pass |
| A full message sync does not remove associations absent from the provider result | Deleted or moved external messages remain visible in the channel | Diff the full provider result against channel associations and clean orphan messages and threads |
| A remote attachment is saved with an unsupported or system-only file identity | The workspace stores a file that is not useful to a member | Filter mail-system files and inline images before creating remote file records |
| A provider attachment is missing or the connected account exceeds its fetch limit | A message attachment cannot be read at that time | Resolve content through the message association and provider identity, return not-found cleanly, and rate limit each account |
| A calendar sharing key uses the wrong provider identity | One meeting can duplicate or merge with an unrelated meeting | Use provider-specific sharing keys and channel roles |
| Suppression is checked only during audience selection | A newly unsubscribed person can receive a campaign | Resolve suppression again at final delivery handoff |
| A provider accepts an email but local persistence fails | The email is delivered while local state remains stale | Treat post-send persistence as recoverable and let later sync reconcile it |
| A provider omits message or thread identities and the send uses one shared empty key | Unrelated sent emails can collide or a reply can leave its thread | Fall back to the message header for new sends and the parent thread for replies |
| An attachment upload fails during sent-message persistence | The message can be lost or one failed file can block delivery state | Upload files independently, save the message with successful files, and remove unclaimed temporary copies |
| An inbound recipient does not match a configured email-group channel | The inbound message is not imported | Match the envelope recipient to the configured domain and channel handle before saving |
| A webhook target resolves to a private address | An outbound request can reach an internal service | Apply secure HTTP target checks before delivery |
| A webhook role cannot access the changed record | The external system receives an event that the webhook should not expose | Apply the webhook role's record access gate before queueing delivery |
| Webhook events exceed the workspace delivery limit | Some matching events are not sent immediately | Admit events through the webhook rate limiter before creating delivery jobs |
| An application manifest references an unavailable record, account, or owned logic function | Install, sync, or export cannot produce valid workspace state | Validate stable references during manifest build, sync, and export |
| A manifest removes a connection provider with active accounts | Those accounts must be disconnected before metadata removal can complete | Plan account deletion and token revocation before applying the final migration |
| An application requests media access that is not in the installed manifest | The requested access can no longer be trusted as approved | Intersect approval with current requested permissions and require review when requests change |
| An application health check fails or returns an invalid result | The application may appear unavailable even when the failure is temporary | Report unknown health and keep per-user checks rate limited |
| An application update adds access without approval | A package can gain access without workspace intent | Compare requested capabilities and media permissions with granted permissions before activation |
| An owner uninstalls an application that serves another workspace | Other installations can lose a required server route | Block owner uninstall while dependent installations remain |
| A local source file is outside the project, missing, or collides with a built file | The package can contain unsafe or incomplete application content | Restrict collected files to the project, reject missing imports, and detect output collisions |
| A server returns an invalid plan or an upload target for an unknown file | The CLI can apply the wrong workspace change or lose a file | Validate the application identifier, action shape, file paths, and upload response before apply |
| A destructive change is hidden inside a cascade | Approval can omit a data-dropping deletion | Keep destructive roots visible and report dependent deletes with the root action |
| A pull receives an unsafe asset path or unsupported file folder | Local files can be overwritten outside the project or the pull cannot be trusted | Allow only declared source, dependency, and safe asset paths and reject duplicates |
| A package is published and the caller assumes it is installed | The registry has a package but the workspace has no application state | Keep publish and workspace installation as separate actions |
| The CLI follows a redirect or sends proxy credentials to another host | Credentials can reach an unintended service | Bind requests to the selected target and handle redirects without following them |
| A local environment is downgraded | Database state can be newer than the running image | Block downgrades and use an upgrade that preserves data volumes |
Key files
| File | Why to read it |
|---|---|
| packages/…/connected-account.entity.ts | Defines external account scope, state, credentials, and channel links. |
| packages/…/connection-provider-oauth-flow.service.ts | Shows the application-provider authorization boundary. |
| packages/…/connection-provider-authorization-state.service.ts | Shows signed callback state and one-time flow-secret handling. |
| packages/…/connection-provider-oauth.controller.ts | Shows browser checks, OAuth callbacks, and workspace redirects. |
| packages/…/connection-provider-custom.controller.ts | Shows custom provider browser and notification callbacks. |
| packages/…/discovered-oauth-client.driver.ts | Shows OAuth resource discovery and stored-client reuse. |
| packages/…/connection-provider-api-key-flow.service.ts | Shows API-key account verification and persistence. |
| packages/…/connected-account-refresh-tokens.service.ts | Shows token reuse, refresh, encryption, and provider error handling. |
| packages/…/application-connections-list.service.ts | Shows application account scope, privacy, refresh, and credential access. |
| packages/…/message-channel.entity.ts | Defines message-source scope, filtering, visibility, and sync state. |
| packages/…/calendar-channel.entity.ts | Defines calendar-source scope, visibility, and sync state. |
| packages/…/channel-sync.service.ts | Connects account and provider notices to channel sync. |
| packages/…/messaging-message-list-fetch.service.ts | Shows message discovery, cursor progress, full-sync cleanup, and import scheduling. |
| packages/…/messaging-messages-import.service.ts | Shows message filtering, folder mapping, batch import, and retry state. |
| packages/…/messaging-message.service.ts | Shows idempotent message, thread, draft, and channel-association reconciliation. |
| packages/…/messaging-save-messages-and-enqueue-contact-creation.service.ts | Shows the shared save path for participants, folders, attachments, and contact creation. |
| packages/…/messaging-message-attachment.service.ts | Shows attachment filtering, remote file records, and attachment links. |
| packages/…/messaging-remote-attachment.service.ts | Shows provider-backed attachment retrieval and connected-account fetch limits. |
| packages/…/file.service.ts | Shows the boundary between stored files and provider-backed remote file content. |
| packages/…/inbound-email-import.service.ts | Shows inbound address routing, thread matching, filtering, and cleanup. |
| packages/…/messaging-message-cleaner.service.ts | Shows removal of stale channel links and orphan messages and threads. |
| packages/…/send-email.service.ts | Shows provider send, draft actions, and recoverable sent-message persistence. |
| packages/…/sent-message-persistence.service.ts | Shows sent-message attachment handling and reuse of the import save path. |
| packages/…/sent-message-record-link.service.ts | Shows permission-gated links from sent threads to workspace records. |
| packages/…/call-webhook.job.ts | Shows role-filtered event admission and queued webhook delivery. |
| packages/…/webhook.controller.ts | Shows REST management and access boundaries for webhooks. |
| packages/…/marketplace-query.service.ts | Shows marketplace discovery and the access details shown before installation. |
| packages/…/application-authorization.service.ts | Shows workspace and member application consent and revocation. |
| packages/…/application-install.service.ts | Shows package installation, approval, rollback, lifecycle hooks, and workspace state. |
| packages/…/application-uninstall-runner.service.ts | Shows uninstall dependency checks and lifecycle reporting. |
| packages/…/application-sync.service.ts | Shows how a manifest becomes workspace application state. |
| packages/…/application-manifest-migration.service.ts | Shows manifest references, workflows, validation, and account cleanup. |
| packages/…/application-manifest-apply.service.ts | Shows the shared apply path for installs, upgrades, and CLI development sync. |
| packages/…/application-development.service.ts | Shows local application creation, export, manifest sync, and file delivery. |
| packages/…/manifest-build.ts | Shows how application source becomes a validated manifest. |
| packages/…/manifest-validate.ts | Shows cross-reference, identifier, relation, and layout checks. |
| packages/…/build-application.ts | Shows how application code and assets become deployable files. |
| packages/…/format-app-plan.ts | Shows plan review, secret masking, cascades, and destructive warnings. |
| packages/…/upload-app-files.ts | Shows server-issued file upload and completion. |
| packages/…/publish-app-to-server.ts | Shows package registration and the boundary between publishing and installation. |
| packages/…/run-app-pull-command.ts | Shows remote export, local reconciliation, and pull reporting. |
| packages/…/pull-application.ts | Shows pull planning, protected entities, fingerprints, and writes. |
| packages/…/resolve-target.ts | Shows explicit remote selection and credential recovery. |
| packages/…/create-target-fetch.ts | Shows target-bound requests, proxy handling, limits, and transport errors. |