Submit association communication requests

Purpose

Applications submit association mail with durable request identity and inspectable acceptance outcomes.

How It Works

A macroservice constructs a request using a known purpose and recipient contract. Submission validates the envelope before storing request data. Object storage precedes the pointer inserted in the business transaction. The committed pointer enables dispatch, while rollback may leave a temporary orphan object. Processing resolves templates or caller content and records acceptance or blocking reasons. Recipient safeguards produce queued or withheld message records under derived identities. Platform pins rendering inputs for later inspection. HTTP and IAM boundaries provide different authenticated entry points to the same request processing.

The rule rows define this outcome; the acceptance set identifies existing proof and proposed checks. Implementation evidence alone does not approve the observed details.

Relationships

Published association content is required for Platform-rendered purposes; caller-rendered purposes follow their separate contract.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Valid communication requests create recipient messages and retained request content.Rendering mode and version constraints reject inconsistent stored requests.
Surfaces: apijob
Intent sources: services-platform:docs/communications/architecture.md#15. Decisions for Andrewservices-platform:docs/communications/architecture.md#2026-10-09 — Final acceptanceservices-platform:docs/communications/architecture.md#18. Rework 2026-10-10: queue pointers, S3 for request data and bodies, SQS owns retriesservices-platform:docs/communications/architecture.md#18. Rework 2026-10-10: queue pointers, S3 for request data and bodies, SQS owns retries

Controls

32 controls apply, from the corpus control catalogue.

TC-AVL-001 TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-IAM-006 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-PRV-004 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

Key	Checked at	Scope
`platform.communications.request`	api	tenant

Business Rules

16 rules, 14 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	A submitting macroservice stores the request object and then inserts its pointer using the communications capability role within its business transaction; only a committed pointer makes the request available for dispatch. origin: services-platform:docs/communications/architecture.md#18.12 One S3 write inside the caller's transaction no proof recorded yet	invariant	database, service	test services-platform:modules/communications/tests/integration/db/communication-request-submissions.table.integration.spec.js#leaves no queue row behind when the caller’s transaction rolls back
`02`must prove Proposed	The capability role inserts caller-owned pointer fields within its workspace only; Claim and ordering fields, existing queue entries, messages and templates are inaccessible. no proof recorded yet	permission	database	test services-platform:modules/communications/tests/integration/db/communication-request-submissions.table.integration.spec.js#cannot read back even the rows it wrote
`03`must prove Proposed	Workspace, submitting service and idempotency key derive the request identifier; Repetition returns a duplicate receipt and preserves one entry, including handoff gaps; lost queue entries can be restored without changing request identity. no proof recorded yet	invariant	service, database	test services-platform:modules/communications/tests/integration/services/requests/submit-request.integration.spec.js#is still answered duplicate, because the request object says the id was submitted before
`04`must prove Proposed	Submission checks workspace, purpose, key, submitter, recipient shape, Marketing fields and caller-rendered content; invalid envelopes write nothing and do not consume their keys. no proof recorded yet	validation	api, service	test services-platform:modules/communications/tests/e2e/requests.e2e.spec.js#takes nothing for that request, so its key is still free
`05`must prove Proposed	Queued processing records acceptance, suppression, invalid fields or configuration-blocking reasons, including missing, archived or unpublished templates, incompatible versions and render failures, for later inspection. no proof recorded yet	lifecycle	service	test services-platform:modules/communications/tests/e2e/requests.e2e.spec.js#blocks a request that names no template, recording the reason staff can act on
`06`must prove Proposed	Acceptance pins a published version and renders each recipient once; Derived message identifiers represent either queued delivery or safeguard withholding. no proof recorded yet	calculation	service	test services-platform:modules/communications/tests/integration/lifecycle/contact-role-compliance-communication.integration.spec.js#accepts the request with the owner’s published version pinned
`07`must prove Proposed	Processing verifies the request object's workspace and request identity against its pointer; missing and mismatched objects become invalid rather than sending. no proof recorded yet	validation	service	test services-platform:modules/communications/tests/integration/services/storage/communication-objects.integration.spec.js#refuses an object that names another tenant, which is what the grant cannot prevent
`08`must prove Proposed	Platform injects association name and message reference into every rendering, replacing caller values for those reserved inputs. no proof recorded yet	invariant	service	test services-platform:modules/communications/tests/integration/services/communication-reads.integration.spec.js#sets the association over whatever the caller sent under that name, so a caller cannot rename the association
`09`must prove Proposed	Caller-rendered purposes accept the supplied subject and HTML unchanged, derive absent text and allow bounded attachments without templates; Platform-rendered purposes reject supplied content and attachments. no proof recorded yet	policy	service	test services-platform:modules/communications/tests/integration/services/dispatch/caller-rendered.integration.spec.js#derives the text part from the HTML when the caller sent none
`10`must prove Proposed	Optional sender display name, reply-to and copies never let the caller choose the sending address; Display names cannot be addresses; recipient safeguards check copies and remove copies matching the primary recipient. no proof recorded yet	validation	service	test services-platform:modules/communications/tests/integration/services/dispatch/caller-rendered.integration.spec.js#sends from the tenant's sender address, under the caller's display name
`11`must prove Proposed	Marketing sends render the specifically pinned message version, including older published versions; missing versions, ownership or purpose mismatches and newer unsupported contracts block sending. no proof recorded yet	validation	service	test services-platform:modules/communications/tests/integration/services/dispatch/owned-template.integration.spec.js#still sends a version that is no longer its template’s current one, and sends the pinned content
`12` Proposed	Transactional compliance mail ignores a contact's general e-mail opt-out, while address suppression still withholds delivery. origin: services-platform:docs/communications/architecture.md#15. Decisions for Andrew	policy	service	documented services-platform:docs/communications/architecture.md#15. Decisions for Andrew
`13` Proposed	IAM also provides readiness, owned-template access, tests, previews and changed-message feeds; missing actors and unsupported operations are refused with the supported-operation list.	validation	service	test services-platform:modules/communications/tests/integration/services/requests/handle-invocation.integration.spec.js#refuses an operation it does not have, naming the ones it does
`14`must prove Proposed	HTTP request submission requires a system caller and communication-request permission; console callers are rejected. no proof recorded yet	permission	api	test services-platform:modules/communications/tests/e2e/requests.e2e.spec.js#refuses a console caller the system route that asks for a communication
`15`must prove Proposed	Request-object storage precedes database commit; a rollback can therefore leave an object without a queue pointer until storage lifecycle cleanup. no proof recorded yet	invariant	service	inferred services-platform:docs/communications/architecture.md#18.12 One S3 write inside the caller's transaction
`16`must prove Proposed	Message persistence accepts Platform or caller rendering only; Platform-rendered non-test messages require a template version; draft test messages may omit it; caller-rendered messages cannot name a template version. no proof recorded yet	validation	database	test services-platform:modules/communications/tests/integration/db/communication-messages.table.integration.spec.js#refuses a transactional message Platform rendered, by the version check’s name

Scenarios

Id	Given	When	Then	Provenance
`01`	CRM submits compliance mail for a source record whose organization type has no template.	Queued acceptance evaluates its configuration.	No message sends; the request records missing-template blockage with purpose and owner information.	test services-platform:modules/communications/tests/integration/lifecycle/contact-role-compliance-communication.integration.spec.js#stores configuration_blocked behind the queue, naming the purpose and the record that owns no template

Planning

Submit association communication requests ​

Purpose ​

How It Works ​

Relationships ​