coordination-engine/history/260601-HybridmailAdapterSpecification.md

HybridmailAdapterSpecification.md

1. Document Status

Document: HybridmailAdapterSpecification.md Project: hybridmail-connect Target Integration: coordination-engine Adapter Contract: AdapterInterfaceSpecification.md v1.0 Status: Draft v1.0 Primary Scope: Hybrid mail submission, production, postal handover, return-mail evidence, registered/delivery-confirmation variants, and vendor-specific hybrid-mail provider integration.

2. Purpose

This document specifies how hybridmail-connect models hybrid mail as a communication, delivery, and evidence channel and how it integrates with coordination-engine.

Hybrid mail means that a digital payload, usually a PDF document, is submitted to a provider that performs physical production and postal dispatch. The provider may validate the document, print it, fold it, insert it into an envelope, frank it, hand it over to a postal carrier, and optionally provide tracking, return-mail information, registered-mail evidence, or delivery-confirmation evidence.

Unlike email, SMS, RSS, or XMPP, hybrid mail has a physical production and delivery chain. The adapter therefore needs to model both digital submission and physical fulfillment.

The goal of this specification is to define a provider-neutral hybrid-mail baseline that can be implemented in vendor-specific flavors for providers such as:

• Deutsche Post / E-POSTBUSINESS API
• Pingen
• Binect
• future hybrid-mail providers

The adapter MUST support a superset model with capability flags, because providers differ in document validation, upload flow, print options, postal products, return-mail processing, preview handling, status granularity, webhooks, registered-letter support, and international delivery.

3. Core Principle

Hybrid mail is a controlled physical-delivery channel initiated through digital submission.

The adapter MUST distinguish:

digital submission
provider acceptance
document validation
production readiness
print production
enveloping
franking
handover to postal carrier
postal delivery evidence
registered or tracked delivery evidence
undeliverable / return-mail evidence
physical delivery uncertainty
coordination result evidence

Normal physical letter dispatch usually cannot prove that the intended recipient personally received, opened, read, understood, or acted on the payload.

The adapter reports hybrid-mail evidence. coordination-engine decides whether that evidence satisfies the coordination case.

4. Architectural Role

4.1 Standalone Role

As a standalone component, hybridmail-connect provides:

• provider-neutral hybrid-mail submission
• PDF upload and document registration
• single-letter and bulk/serial-letter handling
• document validation
• address validation result normalization
• print and shipping option abstraction
• attachment handling
• preview retrieval where supported
• production status tracking
• postal handover status tracking
• return-mail/undeliverable processing
• registered-mail or delivery-confirmation tracking where supported
• vendor-specific provider abstraction
• hybrid-mail timeline and evidence assessment
• provider health and cutoff-time diagnostics
• normalized hybrid-mail evidence events

4.2 coordination-engine Adapter Role

As a coordination-engine adapter, hybridmail-connect provides:

Actions

• delivery.submit_payload
• delivery.submit_letter
• delivery.submit_bulk
• delivery.validate_payload
• delivery.add_attachment
• delivery.set_options
• delivery.request_preview
• delivery.approve_for_sending
• delivery.cancel
• delivery.request_status
• delivery.request_return_info
• delivery.request_registered_tracking
• notification.register_tracking_context

Signals

• payload.validation_failed
• payload.validation_passed
• delivery.payload.submitted
• delivery.payload.accepted
• delivery.payload.rejected
• delivery.payload.available
• delivery.production.pending
• delivery.production.started
• delivery.production.completed
• delivery.postal.handed_over
• delivery.postal.in_transit
• delivery.postal.delivered
• delivery.postal.delivery_confirmed
• delivery.postal.undeliverable
• delivery.postal.return_received
• delivery.postal.forwarded
• delivery.postal.address_corrected
• delivery.postal.status_unknown
• delivery.postal.expired_without_final_status
• system.provider.degraded
• system.provider.unavailable

Some of these normalized events will not be available for all vendors. Provider flavors MUST declare which ones they support.

5. Relationship to coordination-engine

hybridmail-connect does not own:

• CoordinationCase
• intended result evaluation
• participant-level success
• case-level success
• legal notice interpretation
• proof that the recipient opened or read the letter
• contract acceptance
• payment settlement
• signature completion
• follow-up and escalation policy

hybridmail-connect owns:

• hybrid-mail provider abstraction
• document submission
• provider identifiers
• document validation result mapping
• print/shipping option mapping
• status polling and webhook ingestion
• physical-production status normalization
• postal-handover status normalization
• return-mail / undeliverable status normalization
• registered-letter or delivery-confirmation evidence normalization
• hybrid-mail-native message timeline
• hybrid-mail evidence assessment

The boundary rule is:

hybridmail-connect reports what happened in the hybrid-mail channel and what that may indicate. coordination-engine decides what that means for the coordination case.

6. Hybrid Mail as Delivery Channel

Within coordination-engine, hybrid mail is primarily a delivery channel, not just a notification channel.

It is used when the communication payload itself is physically delivered as a paper letter.

Examples:

PDF letter submitted for physical mailing
invoice printed and posted
contract notice sent by post
dunning letter sent as registered mail
mass mailing sent as bulk/serial letters
confidential employee payroll letter mailed physically

Hybrid mail may also produce notification-like evidence, because physical payload delivery is often treated as a strong delivery attempt. However, even physical delivery normally does not prove that the intended human personally read the letter.

For high-assurance scenarios, hybrid-mail evidence may be combined with:

• registered-mail evidence
• delivery confirmation
• return-mail processing
• manual evidence
• recipient response
• payment event
• signature event
• portal access
• acknowledgement

7. Provider Landscape and Superset Baseline

The public provider material suggests the following baseline capabilities.

7.1 Deutsche Post / E-POSTBUSINESS API Baseline

The Deutsche Post E-POSTBUSINESS API supports automated digital submission of PDF documents for physical mail shipment. It includes PDF upload, single and bulk processing, status requests, registered-letter use cases, German and international receivers, and requires attention to PDF/A-1b, address and layout requirements, metadata, and size constraints. It uses authenticated API access and rate limits. It provides process state and delivery/error information where available.

7.2 Pingen Baseline

Pingen supports a letter API with SDKs, OAuth-style client credential examples, file upload, letter creation, configurable address position, auto-send control, idempotency-key headers, rate limiting, configurable send limits, staging/sandbox, Track & Trace, webhooks, document validation, print and delivery options, return-mail processing, and delivery-confirmation-related webhook categories.

Pingen explicitly distinguishes status tracking through handover and return-mail processing from ordinary post-office delivery confirmation. This is central for evidence grading.

7.3 Binect Baseline

Binect exposes a REST/Swagger API for digital letter dispatch with workflows such as document upload, attachment upload, shipping option configuration, preview retrieval, sending, and status queries. It validates uploaded documents for postal suitability, including address position, address format, and restricted areas. It supports single and serial/bulk letter concepts and provides shipping/production status information.

7.4 Superset Design Implication

The adapter MUST define a provider-neutral superset and require each provider flavor to expose a capability descriptor.

Capabilities should be feature-gated rather than assumed.

Examples:

supports_preview
supports_webhooks
supports_polling
supports_bulk_upload
supports_serial_letters
supports_attachments
supports_registered_mail
supports_delivery_confirmation
supports_return_mail
supports_address_correction
supports_international_mail
supports_pdfa_validation
supports_color_option
supports_duplex_option
supports_envelope_selection
supports_cancel_before_production
supports_staging_environment

8. Hybrid Mail Lifecycle Model

hybridmail-connect models a hybrid-mail delivery as a lifecycle with observable phases.

letter.created
letter.payload_received
letter.rendered
letter.render_failed
letter.upload_requested
letter.accepted_by_adapter
letter.rejected_by_adapter
letter.uploaded_to_provider
letter.accepted_by_provider
letter.rejected_by_provider
letter.validation_started
letter.validation_passed
letter.validation_failed
letter.action_required
letter.preview_available
letter.options_set
letter.ready_for_sending
letter.submitted_for_sending
letter.cancelled_before_production
letter.processing_started
letter.transferred_for_printing
letter.printed
letter.enveloped
letter.franked
letter.handed_to_postal_service
letter.in_postal_delivery
letter.delivered_confirmed
letter.registered_delivery_event
letter.undeliverable_reported
letter.return_mail_received
letter.address_corrected
letter.forwarded
letter.finalized
letter.status_unknown
letter.expired_without_final_status

The lifecycle is provider-dependent. Not every provider exposes every state.

The lifecycle is also not strictly linear. Late return-mail events may arrive after a letter was previously considered handed over or even after a case moved to another state.

9. Letter, Document, Attempt, Batch, and Recipient Model

The adapter MUST distinguish at least six layers.

9.1 HybridmailLetter

The logical letter delivery created by a client or coordination case.

HybridmailLetter:
  hybridmail_letter_id: string
  coordination_case_id: string?
  participant_id: string?
  purpose: string?
  payload_ref: ResourceRef
  document_ref: HybridmailDocumentRef?
  recipient: PostalRecipient
  sender: PostalSender?
  options: HybridmailOptions?
  tracking_context: TrackingContext
  created_at: timestamp

9.2 HybridmailDocumentRef

The submitted document or generated print artifact.

HybridmailDocumentRef:
  document_id: string
  provider_document_id: string?
  document_type: pdf | pdfa | postscript | other
  version: string?
  page_count: integer?
  sheet_count: integer?
  color_pages: integer?
  grayscale_pages: integer?
  simplex_pages: integer?
  duplex_pages: integer?
  integrity_hash: string?
  validation_state: unknown | pending | passed | action_required | failed
  metadata: object?

9.3 HybridmailAttempt

One submission attempt through one provider/configuration.

HybridmailAttempt:
  hybridmail_attempt_id: string
  hybridmail_letter_id: string
  provider_name: string
  provider_account_ref: string?
  provider_document_id: string?
  provider_letter_id: string?
  provider_sending_id: string?
  provider_tracking_id: string?
  state: HybridmailAttemptState
  created_at: timestamp
  updated_at: timestamp

9.4 HybridmailBatch

A batch or serial-letter group.

HybridmailBatch:
  batch_id: string
  provider_batch_id: string?
  coordination_case_id: string?
  batch_type: bulk | serial | campaign | mixed | unknown
  letters:
    - hybridmail_letter_id
  state: HybridmailBatchState
  created_at: timestamp
  updated_at: timestamp

A batch can have partial success. Each child letter must retain its own evidence state.

9.5 PostalRecipient

The postal recipient extracted, provided, or inferred.

PostalRecipient:
  recipient_id: string?
  name_lines:
    - string
  organization: string?
  street: string?
  house_number: string?
  address_addition: string?
  postal_code: string?
  city: string?
  region: string?
  country_code: string?
  country_name: string?
  address_source: extracted_from_document | provided_metadata | provider_detected | manual | unknown
  address_quality: PostalAddressQuality?

9.6 PostalSender

PostalSender:
  sender_id: string?
  name_lines:
    - string
  organization: string?
  return_address: PostalRecipient?
  billing_account_ref: string?
  sender_identity_ref: string?

10. Hybrid Mail Options Model

The adapter MUST support a provider-neutral print and postal option model.

HybridmailOptions:
  color_mode: color | grayscale | provider_default | unknown
  print_sides: simplex | duplex | provider_default | unknown
  envelope_type: c5 | c4 | window_left | window_right | no_window | provider_default | unknown
  address_position: left | right | metadata | extracted | provider_default | unknown
  postage_product: standard | priority | economy | registered | registered_return_receipt | delivery_confirmation | international | dialogpost | provider_specific
  country_scope: domestic | international | mixed | unknown
  dispatch_mode: manual_review | auto_send | submit_later | scheduled
  desired_dispatch_date: date?
  cutoff_policy_ref: string?
  return_mail_handling: none | provider_processed | scan_return | digital_return_info | physical_return | unknown
  address_correction_requested: boolean?
  sustainability_option: none | carbon_reduced | provider_default | provider_specific
  metadata: object?

Provider flavors MUST map their native options into this model and declare unsupported fields.

11. Document Validation Model

Document validation is central to hybrid mail.

HybridmailValidationResult:
  document_id: string
  validation_state: pending | passed | action_required | failed | unknown
  issues:
    - HybridmailValidationIssue
  validated_at: timestamp?
  provider_validation_ref: string?

HybridmailValidationIssue:
  issue_code: string
  severity: info | warning | action_required | fatal
  category: format | page_size | pdfa | address | restricted_area | margins | file_size | page_count | metadata | attachment | postage | country | provider_policy | unknown
  message: string
  page_number: integer?
  bounding_box: object?
  fixable: boolean?

Common validation categories:

invalid_pdf
invalid_pdfa
unsupported_file_type
not_a4_portrait
invalid_page_size
file_too_large
too_many_pages
address_not_detected
address_invalid
address_position_invalid
restricted_area_violation
barcode_area_violation
margin_violation
unsupported_country
unsupported_product
attachment_invalid
insufficient_credit

Validation failure usually maps to strong failure of the hybrid-mail attempt, but not necessarily failure of the coordination case if another channel or corrected document can be used.

12. Preview Model

Some providers support preview retrieval before dispatch.

HybridmailPreview:
  preview_id: string
  document_id: string
  provider_preview_id: string?
  preview_type: pdf | png | image | metadata | unknown
  preview_uri: string?
  generated_at: timestamp
  expires_at: timestamp?
  metadata: object?

Preview evidence maps to operational readiness, not physical delivery.

13. Hybrid Mail Evidence Assessment

hybridmail-connect should provide a hybrid-mail-native assessment separate from coordination-engine state.

HybridmailEvidenceAssessment:
  hybridmail_letter_id: string
  participant_id: string?
  category: success | fail | undef
  subclass: string
  confidence: low | medium | high
  strongest_signal: string?
  evidence_summary:
    - string
  recommended_coordination_interpretation: string?

The assessment categories are adapter-level hints.

13.1 Hybrid-Mail Adapter Success

Hybrid-mail-level success means the channel produced strong hybrid-mail evidence.

Possible subclasses:

success.provider_accepted
success.validation_passed
success.submitted_for_sending
success.production_started
success.transferred_for_printing
success.handed_to_postal_service
success.registered_delivery_event
success.delivery_confirmed
success.return_info_processed

Important: These are not automatically coordination success.

For ordinary letters, success.handed_to_postal_service is strong dispatch evidence but not proof of physical delivery or human awareness.

13.2 Hybrid-Mail Adapter Fail

Hybrid-mail-level fail indicates strong evidence that the hybrid-mail attempt failed.

Subclasses:

fail.missing_payload
fail.invalid_document
fail.validation_failed
fail.action_required_unresolved
fail.invalid_address
fail.unsupported_country
fail.unsupported_product
fail.insufficient_credit
fail.provider_rejected
fail.upload_failed
fail.production_failed
fail.cancelled
fail.postal_undeliverable
fail.return_mail_received
fail.expired_before_handover

13.3 Hybrid-Mail Adapter Undef

Hybrid-mail-level undef is used when the adapter cannot determine physical delivery, recipient awareness, or final postal outcome.

Subclasses:

undef.pending
undef.uploaded_only
undef.provider_accepted_only
undef.validation_pending
undef.ready_but_not_sent
undef.submitted_for_sending
undef.processing
undef.transferred_for_printing
undef.handed_to_postal_service_but_delivery_unproven
undef.postal_delivery_unknown
undef.registered_tracking_pending
undef.return_mail_pending
undef.no_final_status_expected
undef.conflicting_evidence
undef.channel_degraded

For ordinary physical letters, the adapter should expect undef.handed_to_postal_service_but_delivery_unproven to be common.

14. Detailed Scenario Classification

14.1 Pre-Submission Scenarios

Scenario	Hybridmail assessment	Normalized event	Notes
Missing PDF/payload	fail.missing_payload	delivery.payload.failed	No delivery possible
Unsupported document format	fail.invalid_document	payload.validation_failed	Provider may reject
Invalid PDF/PDF-A	fail.validation_failed	payload.validation_failed	Provider-specific
Non-A4 or unsupported page size	fail.validation_failed	payload.validation_failed	Common hybrid-mail constraint
Address not detected	fail.invalid_address or action_required	payload.validation_failed	May be fixable
Address in wrong window position	fail.validation_failed or action_required	payload.validation_failed	Provider-specific
Restricted area violation	fail.validation_failed or action_required	payload.validation_failed	Print/postal layout issue
Unsupported destination country	fail.unsupported_country	delivery.payload.rejected	Route unavailable
Unsupported postal product	fail.unsupported_product	delivery.payload.rejected	Option mismatch
Insufficient credit/account problem	fail.insufficient_credit	delivery.payload.rejected	Operational/account failure
Provider unavailable before acceptance	undef.pending or provider fail	action error	Retry-dependent

14.2 Upload and Validation Scenarios

Scenario	Hybridmail assessment	Normalized event	Notes
Adapter accepted request	undef.pending	delivery.payload.submitted	Adapter accepted work
Provider accepted upload	undef.provider_accepted_only	delivery.payload.accepted	Digital submission accepted
Provider rejected upload	fail.provider_rejected	delivery.payload.rejected	Strong attempt failure
Validation started	undef.validation_pending	payload.validation_started	Operational status
Validation passed	success.validation_passed	payload.validation_passed	Ready for options/send
Action required	fail.action_required_unresolved or undef	payload.validation_failed with severity	May be fixable
Validation failed fatal	fail.validation_failed	payload.validation_failed	Cannot send
Preview available	operational success	delivery.payload.available	Review evidence only
Attachment accepted	operational success	delivery.payload.accepted with attachment metadata	Not final delivery
Attachment failed	fail.validation_failed	payload.validation_failed	Must be corrected

14.3 Sending and Production Scenarios

Scenario	Hybridmail assessment	Normalized event	Notes
Options set	operational success	metadata event	Not delivery
Ready for sending	undef.ready_but_not_sent	delivery.payload.available	Awaiting dispatch approval
Submitted for sending	success.submitted_for_sending	delivery.payload.submitted	Provider instructed to send
Cancelled before production	fail.cancelled or cancelled	delivery.payload.failed or manual cancellation	Depends on policy
Processing started	undef.processing	delivery.production.started	Production chain began
Transferred for printing	success.transferred_for_printing	delivery.production.started	Strong production evidence
Printed	production success	delivery.production.completed	Not postal handover
Enveloped/franked	production success	delivery.production.completed	Not postal delivery
Production failed	fail.production_failed	delivery.payload.failed	Strong channel failure
Handover to postal service	success.handed_to_postal_service	delivery.postal.handed_over	Strong dispatch evidence
Same-day cutoff missed	undef.processing or delayed	metadata/channel warning	Adjust expected timing

14.4 Postal Delivery Scenarios

Scenario	Hybridmail assessment	Normalized event	Notes
Ordinary letter handed over	undef.handed_to_postal_service_but_delivery_unproven	delivery.postal.handed_over	Strong dispatch, delivery unproven
Postal tracking ID received	undef.postal_delivery_unknown	delivery.postal.in_transit	Stronger traceability
Registered tracking event	success.registered_delivery_event	delivery.postal.in_transit or confirmed	Depends event
Delivery confirmed	success.delivery_confirmed	delivery.postal.delivery_confirmed	Strong physical delivery evidence
Return receipt received	success.delivery_confirmed	delivery.postal.delivery_confirmed	Stronger evidence
Undeliverable reported	fail.postal_undeliverable	delivery.postal.undeliverable	Strong negative evidence
Return mail received	fail.return_mail_received	delivery.postal.return_received	Strong negative evidence
Address corrected	operational/address evidence	delivery.postal.address_corrected	May support future correction
Forwarded due to moving	undef.forwarded or success-ish	delivery.postal.forwarded	Delivery path changed
No final status expected	undef.no_final_status_expected	metadata	Common for ordinary letters
No return after waiting period	still undef unless policy accepts	timeout metadata	Absence of return is not proof

14.5 Batch / Serial Letter Scenarios

Scenario	Hybridmail assessment	Normalized event	Notes
Batch accepted	batch-level pending	delivery.payload.submitted	Child states needed
Some children validation-failed	partial	per-letter payload.validation_failed	Batch partial state
Some children ready	partial success	per-letter validation passed	Each letter tracked
Batch submitted	batch-level submitted	delivery.payload.submitted	Not each delivery
Some children handed over	partial dispatch	per-letter handover	Case aggregation needed
Some children undeliverable	partial negative	per-letter return/undeliverable	Do not fail whole batch blindly

15. Adapter-to-Coordination Mapping

15.1 Core Mapping Table

Hybridmail-native event	Hybridmail assessment	coordination-engine event	Coordination interpretation
Letter created	undef.pending	delivery.payload.submitted	Local delivery object exists
Provider upload accepted	undef.provider_accepted_only	delivery.payload.accepted	Digital submission accepted
Provider upload rejected	fail.provider_rejected	delivery.payload.rejected	Strong attempt failure
Validation passed	success.validation_passed	payload.validation_passed	Production-ready
Validation failed	fail.validation_failed	payload.validation_failed	Must correct or fallback
Preview available	operational success	delivery.payload.available	Review evidence
Ready for sending	undef.ready_but_not_sent	delivery.payload.available	Awaiting send
Submitted for sending	success.submitted_for_sending	delivery.payload.submitted	Provider instructed
Processing started	undef.processing	delivery.production.started	Production began
Transferred for printing	success.transferred_for_printing	delivery.production.started	Strong production evidence
Production completed	production success	delivery.production.completed	Printed/enveloped/franked
Handed to post	success.handed_to_postal_service	delivery.postal.handed_over	Strong dispatch evidence
Tracking ID received	stronger tracking evidence	delivery.postal.in_transit	Physical route traceability
Delivery confirmed	success.delivery_confirmed	delivery.postal.delivery_confirmed	Strong delivery evidence
Undeliverable	fail.postal_undeliverable	delivery.postal.undeliverable	Strong negative evidence
Return mail received	fail.return_mail_received	delivery.postal.return_received	Strong negative evidence
Address corrected	address signal	delivery.postal.address_corrected	Useful for contact registry
Cancelled	fail.cancelled	delivery.payload.failed or manual cancellation	Attempt stopped

15.2 Coordination Undef Subclasses

coordination-engine may derive these uncertainty classes from hybrid-mail evidence:

undef.pending
undef.provider_accepted_only
undef.validation_pending
undef.ready_but_not_sent
undef.production_pending
undef.handed_to_postal_service_but_delivery_unproven
undef.postal_delivery_unknown
undef.no_final_status_expected
undef.return_mail_pending
undef.conflicting_evidence
undef.channel_degraded
undef.escalation_required

Hybrid mail commonly produces:

undef.handed_to_postal_service_but_delivery_unproven
undef.no_final_status_expected
undef.return_mail_pending

for ordinary letters.

16. Evidence Grading Rules

16.1 Provider Upload Accepted

event_type: delivery.payload.accepted
evidence_grade:
  strength: weak
  actor_certainty: none
  authority_certainty: none
  payload_certainty: medium
  interaction_certainty: none
  timing_certainty: medium
  channel_certainty: medium
  non_repudiation_strength: low
notes:
  - Provider accepted the digital submission.
  - Does not prove validation, production, postal handover, or delivery.

16.2 Validation Passed

event_type: payload.validation_passed
evidence_grade:
  strength: medium
  actor_certainty: none
  authority_certainty: none
  payload_certainty: high
  interaction_certainty: none
  timing_certainty: high
  channel_certainty: high
  non_repudiation_strength: low
notes:
  - Document passed provider validation for print/postal processing.
  - Does not prove dispatch or delivery.

16.3 Validation Failed

event_type: payload.validation_failed
evidence_grade:
  strength: negative
  actor_certainty: none
  authority_certainty: none
  payload_certainty: high
  interaction_certainty: none
  timing_certainty: high
  channel_certainty: high
  non_repudiation_strength: low
notes:
  - Document cannot be processed until corrected or replaced.

16.4 Submitted for Sending

event_type: delivery.payload.submitted
evidence_grade:
  strength: medium
  actor_certainty: none
  authority_certainty: none
  payload_certainty: high
  interaction_certainty: none
  timing_certainty: high
  channel_certainty: high
  non_repudiation_strength: low
notes:
  - Letter was submitted into the provider sending process.
  - Does not prove print production or postal handover.

16.5 Transferred for Printing

event_type: delivery.production.started
evidence_grade:
  strength: medium
  actor_certainty: none
  authority_certainty: none
  payload_certainty: high
  interaction_certainty: none
  timing_certainty: high
  channel_certainty: high
  non_repudiation_strength: low
notes:
  - Letter was transferred to or started in print production.
  - Does not prove postal handover.

16.6 Handed to Postal Service

event_type: delivery.postal.handed_over
evidence_grade:
  strength: strong
  actor_certainty: none
  authority_certainty: none
  payload_certainty: high
  interaction_certainty: none
  timing_certainty: high
  channel_certainty: high
  non_repudiation_strength: medium
notes:
  - Letter was handed over to the postal delivery chain.
  - Strong dispatch evidence.
  - Does not prove recipient receipt or reading.

16.7 Delivery Confirmed / Registered Event

event_type: delivery.postal.delivery_confirmed
evidence_grade:
  strength: strong
  actor_certainty: low
  authority_certainty: none
  payload_certainty: high
  interaction_certainty: low
  timing_certainty: high
  channel_certainty: high
  non_repudiation_strength: medium
notes:
  - Postal delivery confirmation or registered-mail event was received.
  - This is strong physical-delivery evidence.
  - It may still not prove that the intended human personally read the payload.

16.8 Return Mail / Undeliverable

event_type: delivery.postal.return_received
evidence_grade:
  strength: negative
  actor_certainty: none
  authority_certainty: none
  payload_certainty: high
  interaction_certainty: none
  timing_certainty: high
  channel_certainty: high
  non_repudiation_strength: medium
notes:
  - Letter was returned or reported undeliverable.
  - Strong evidence that physical delivery failed for this attempt.

16.9 Address Correction

event_type: delivery.postal.address_corrected
evidence_grade:
  strength: medium
  actor_certainty: none
  authority_certainty: none
  payload_certainty: medium
  interaction_certainty: none
  timing_certainty: high
  channel_certainty: high
  non_repudiation_strength: low
notes:
  - Postal process or provider supplied address correction information.
  - Useful for future delivery attempts and contact registry updates.

17. Status Timeline API

hybridmail-connect SHOULD expose a delivery timeline suitable for standalone diagnostics and coordination audit.

HybridmailTimeline:
  hybridmail_letter_id: string
  provider_name: string
  provider_document_id: string?
  provider_letter_id: string?
  provider_sending_id: string?
  provider_tracking_id: string?
  events:
    - HybridmailTimelineEvent
  current_assessment: HybridmailEvidenceAssessment

HybridmailTimelineEvent:
  event_id: string
  event_type: string
  occurred_at: timestamp
  source: adapter | provider | print_center | postal_carrier | return_mail | operator
  native_event_type: string?
  normalized_event_type: string?
  summary: string
  evidence_grade: EvidenceGrade
  raw_event_ref: string?

18. Adapter Descriptor

hybridmail-connect MUST expose an AdapterDescriptor compatible with AdapterInterfaceSpecification.md v1.0.

adapter_id: hybridmail-connect.default
adapter_name: hybridmail-connect
adapter_version: 1.0.0
adapter_contract_version: 1.0
adapter_types:
  - delivery
  - communication
  - document
  - archive
provider_family: hybridmail
provider_name: configurable
deployment_mode: external
supported_channels:
  - hybridmail
  - postal_mail
supported_endpoint_types:
  - postal_address
supported_actions:
  - action_type: delivery.submit_letter
    mode: async
    idempotency_required: true
  - action_type: delivery.submit_bulk
    mode: async
    idempotency_required: true
  - action_type: delivery.validate_payload
    mode: async
    idempotency_required: true
  - action_type: delivery.add_attachment
    mode: async
    idempotency_required: true
  - action_type: delivery.set_options
    mode: sync
    idempotency_required: true
  - action_type: delivery.request_preview
    mode: async
    idempotency_required: true
  - action_type: delivery.approve_for_sending
    mode: async
    idempotency_required: true
  - action_type: delivery.cancel
    mode: async
    idempotency_required: true
  - action_type: delivery.request_status
    mode: sync
    idempotency_required: true
emitted_event_types:
  - delivery.payload.submitted
  - delivery.payload.accepted
  - delivery.payload.rejected
  - payload.validation_passed
  - payload.validation_failed
  - delivery.payload.available
  - delivery.production.started
  - delivery.production.completed
  - delivery.postal.handed_over
  - delivery.postal.in_transit
  - delivery.postal.delivery_confirmed
  - delivery.postal.undeliverable
  - delivery.postal.return_received
  - delivery.postal.forwarded
  - delivery.postal.address_corrected
  - delivery.postal.status_unknown
  - system.provider.degraded
  - system.provider.unavailable
evidence_profile:
  strongest_evidence_level: strong
  can_prove_human_awareness: false
  can_prove_payload_delivery: partially
  can_prove_identity: false
identity_profile:
  identity_strength: none_to_low
  authority_strength: none
limitations:
  - Ordinary postal handover does not prove recipient receipt.
  - Ordinary physical letters often do not provide final delivery confirmation.
  - Delivery confirmation depends on postal product and provider support.
  - Return-mail information may arrive late.
  - Address extraction and validation differ by provider.
  - Cancellation may only be possible before production starts.
  - Batch-level status does not imply child-letter success.

19. Provider Flavor Descriptor

Each vendor-specific implementation MUST expose a HybridmailProviderFlavorDescriptor.

HybridmailProviderFlavorDescriptor:
  provider_name: dpag_epost | pingen | binect | other
  provider_version: string?
  supported_file_types:
    - pdf
    - pdfa
    - postscript
  supports_single_letter: boolean
  supports_bulk: boolean
  supports_serial_letters: boolean
  supports_attachments: boolean
  supports_preview: boolean
  supports_webhooks: boolean
  supports_polling: boolean
  supports_registered_mail: boolean
  supports_delivery_confirmation: boolean
  supports_return_mail: boolean
  supports_address_correction: boolean
  supports_international_mail: boolean
  supports_cancellation: boolean
  supports_staging: boolean
  supports_idempotency: boolean
  supports_rate_limits: boolean
  supported_print_options:
    color_mode: boolean
    simplex_duplex: boolean
    envelope_selection: boolean
    address_position: boolean
  supported_postal_products:
    - standard
    - priority
    - registered
    - registered_return_receipt
    - delivery_confirmation
    - international
    - dialogpost
    - provider_specific
  cutoff_times:
    - country_scope: string
      cutoff_local_time: string
      notes: string?
  limitations:
    - string

20. Provider Flavor Baseline

20.1 DPAG / E-POSTBUSINESS Flavor

Likely capability baseline:

provider_name: dpag_epost
supports_single_letter: true
supports_bulk: true
supports_serial_letters: true
supports_attachments: provider_specific
supports_preview: provider_specific
supports_webhooks: provider_specific
supports_polling: true
supports_registered_mail: true
supports_delivery_confirmation: registered_product_dependent
supports_return_mail: provider_specific
supports_address_correction: provider_specific
supports_international_mail: true
supports_pdfa_validation: true
supports_staging: true
supports_idempotency: provider_specific
supported_file_types:
  - pdf
  - pdfa

Key flavor notes:

PDF/PDF-A handling is central.
PDF/A-1b knowledge is expected.
Address and layout requirements matter.
Status requests are core.
Registered-letter use cases are supported.
Bulk status information is relevant.
Activation, vendor/customer identifiers, and authenticated API access are central.

20.2 Pingen Flavor

Likely capability baseline:

provider_name: pingen
supports_single_letter: true
supports_bulk: true
supports_serial_letters: true
supports_attachments: provider_specific
supports_preview: true
supports_webhooks: true
supports_polling: true
supports_registered_mail: true
supports_delivery_confirmation: product_dependent
supports_return_mail: true
supports_address_correction: provider_specific
supports_international_mail: true
supports_staging: true
supports_idempotency: true
supported_file_types:
  - pdf

Key flavor notes:

File upload and letter creation are distinct concepts.
Address position can be configured.
Auto-send can be controlled.
Track & Trace provides detailed processing events.
Webhooks cover document issues, sent documents, undeliverable documents, and delivered sent documents.
Return mail processing is a first-class feature.
Normal postal delivery confirmation is not generally available for ordinary letters.

20.3 Binect Flavor

Likely capability baseline:

provider_name: binect
supports_single_letter: true
supports_bulk: true
supports_serial_letters: true
supports_attachments: true
supports_preview: true
supports_webhooks: provider_specific
supports_polling: true
supports_registered_mail: provider_specific
supports_delivery_confirmation: provider_specific
supports_return_mail: provider_specific
supports_address_correction: provider_specific
supports_international_mail: provider_specific
supports_staging: provider_specific
supports_idempotency: provider_specific
supported_file_types:
  - pdf
  - postscript

Key flavor notes:

Document upload is a core workflow.
Attachments can be added.
Print and shipping options can be set.
PDF/PNG preview retrieval is supported.
Sending is performed separately after document preparation.
Status queries are supported.
Validation includes address position, address format, and restricted-area checks.
Default print/shipping options may be inherited and then overridden.

21. Action Request Handling

21.1 delivery.submit_letter

delivery.submit_letter submits a letter payload to a hybrid-mail provider.

Required fields:

request_id
action_type
coordination_case_id
participant_id
payload_ref
target_endpoint
tracking_context
idempotency_key
requested_at

Example:

request_id: req_001
action_type: delivery.submit_letter
coordination_case_id: case_123
participant_id: participant_456
channel: hybridmail
target_endpoint:
  endpoint_type: postal_address
  value: postal_recipient_ref_456
payload_ref:
  ref_type: coordination_payload
  ref_id: payload_777
  uri: s3://bucket/document.pdf
  integrity_hash: sha256:...
content:
  payload_refs:
    - ref_type: coordination_payload
      ref_id: payload_777
tracking_context:
  correlation_id: corr_789
  coordination_case_id: case_123
  participant_id: participant_456
  delivery_id: delivery_001
  payload_id: payload_777
idempotency_key: case_123:participant_456:hybridmail:delivery_001
requested_at: 2026-01-01T12:00:00Z
metadata:
  hybridmail_options:
    color_mode: grayscale
    print_sides: duplex
    envelope_type: window_left
    postage_product: standard

21.2 Action Result

The adapter returns:

request_id: req_001
adapter_id: hybridmail-connect.default
accepted: true
action_state: accepted
adapter_operation_id: hmop_001
provider_operation_id: providerop_001
initial_events:
  - event_type: delivery.payload.submitted
received_at: 2026-01-01T12:00:01Z

This result does not prove validation, production, postal handover, or delivery.

22. Provider Abstraction

hybridmail-connect SHOULD support a provider abstraction layer.

Provider integration responsibilities:

• authenticate
• upload document
• create letter/document record
• add attachments
• configure options
• request preview
• submit for sending
• cancel where possible
• poll status
• ingest webhooks where supported
• normalize provider statuses
• parse validation issues
• parse return-mail information
• parse delivery-confirmation information
• expose provider health

Provider model:

HybridmailProvider:
  provider_name: string
  provider_account_ref: string
  supported_features:
    - upload
    - validation
    - attachments
    - options
    - preview
    - send
    - cancel
    - status_polling
    - webhooks
    - return_mail
    - registered_mail
    - delivery_confirmation
    - bulk
    - staging
  event_mapping_ref: string
  configuration_ref: string

Provider-specific modules should map to the hybrid-mail-native model first, then to normalized coordination events.

Provider event
→ hybridmail-native event
→ HybridmailEvidenceAssessment
→ EvidenceEvent for coordination-engine

23. Native Provider Event Mapping

The adapter MUST support provider-specific mapping files or code modules.

Common provider-native event groups:

uploaded
received
validated
validation_failed
ready
action_required
invalid
preview_available
submitted
processing
transferred_for_printing
printed
enveloped
franked
handed_to_post
sent
tracking_id_receivedered
delivery_confirmed
undeliverable
returned
address_corrected
forwarded
cancelled
failed
unknown

Important mapping rule:

Provider terms such as sent, delivered, or posted MUST be mapped according to the provider’s actual semantics.

For example:

"handed to post" → delivery.postal.handed_over
"delivery confirmed" → delivery.postal.delivery_confirmed
"undeliverable" → delivery.postal.undeliverable

A provider status called delivered MUST NOT automatically mean coordinatit success unless its semantics are documented and the coordination policy accepts it.

24. Return Mail and Undeliverable Model

HybridmailReturnEvent:
  return_event_id: string
  hybridmail_letter_id: string
  provider_return_id: string?
  postal_tracking_id: string?
  return_type: undeliverable | address_unknown | recipient_moved | refused | deceased | insufficient_address | mailbox_inaccessible | other | unknown
  address_correction: PostalRecipient?
  return_document_ref: ResourceRef?
  occurred_at: timestamp?
  observed_at: timestamp
  raw_event_ref: string?

Return events usually create strong negative delivery evidence but may also provide address-correction information useful for future attempts.

25. Registered / Delivery Confirmation Model

HybridmailDeliveryConfirmation:
  confirmation_id: string
  hybridmail_letter_id: string
  provider_tracking_id: string?
  postal_tracking_id: string?
  product_type: registered | registered_return_receipt | delivery_confirmation | provider_specific
  status: in_transit | attempted | delivered | refused | undeliverable | returned | unknown
  recipient_signature_ref: ResourceRef?
  confirmation_document_ref: ResourceRef?
  occurred_at: timestamp?
  observed_at: timestamp
  raw_event_ref: string?

Delivery confirmation is stronger than ordinary handover evidence, but the exact legal and business meaning remains scenario-specific.

26. Address Quality Model

PostalAddressQuality:
  validation_state: unknown | valid | action_required | invalid | corrected
  country_supported: boolean?
  address_position_valid: boolean?
  address_format_valid: boolean?
  postal_code_valid: boolean?
  street_known: boolean?
  recipient_known: boolean?
  correction_available: boolean?
  correction_source: provider | postal_carrier | manual | unknown
  issues:
    - string

Address quality may be emitted as diagnostics and may update a contact registry, but it should not by itself create coordination result success.

27. Channel Health

hybridmail-connect SHOULD expose hybrid-mail channel health.

HybridmailChannelHealth:
  provider_name: string
  provider_account_ref: string?
  status: healthy | degraded | failing | unknown
  authentication_status: valid | expired | missing | insufficient | unknown
  upload_status: healthy | degraded | unavailable | unknown
  validation_status: healthy | degraded | unavailable | unknown
  production_status: healthy | delayed | unavailable | unknown
  postal_handover_status: healthy | delayed | unavailable | unknown
  webhook_status: healthy | degraded | unavailable | not_supported | unknown
  cutoff_status: before_cutoff | after_cutoff | no_production_day | unknown
  known_degradations:
    - string

Health-related normalized events:

system.provider.degraded
system.provider.unavailable
system.adapter.health_changed

28. Security Requirements

hybridmail-connect MUST:

• protect provider credentials
• protect uploaded payloads and document references
• support secure transport to providers
• preserve idempotency
• avoid duplicate physical sends for repeated idempotency keys
• validate provider webhooks where supported
• avoid logging sensitive document content
• protect postal recipient data
• support tenant/account separation where applicable
• support secure deletion or retention rules for raw payloads and previews
• clearly separate test/staging and production modes

Duplicate-send prevention is especially critical because physical mail sends cost money and may have legal/business consequences.

29. Privacy Requirements

hybridmail-connect SHOULD:

• store payload references instead of payload content where possible
• support metadata-only mode
• support masking of postal addresses
• support raw event redaction
• support configurable retention of documents, previews, and raw events
• avoid unnecessary storage of print payloads after submission
• separate operational diagnostics from coordination evidence
• support deletion or anonymization workflows where legally possible
• document provider-side retention limitations

30. Reliability Requirements

hybridmail-connect MUST support:

• idempotent submit requests
• duplicate webhook event detection
• out-of-order event handling
• late return-mail events
• late delivery-confirmation events
• retryable upload failures
• non-retryable validation failures
• provider timeout handling
• provider polling fallback where webhooks are unavailable
• correlation preservation
• dead-letter handling for unprocessable events
• batch partial-failure handling

Late events MUST be preserved.

Example:

Letter handed to postal service on Monday.
Coordination case moves to waiting state.
Return mail event arrives two weeks later.
The return event must still be recorded and emitted as negative evidence.

31. Raw Event Preservation

hybridmail-connect SHOULD preserve raw provider events or references to them.

RawHybridmailEventRef:
  raw_event_id: string
  provider_name: string
  source: api_response | webhook | polling | print_center | postal_carrier | return_mail | operator
  storage_ref: string?
  received_at: timestamp
  redacted: boolean

Normalized events should reference raw event data where available:

raw_event_ref: raw_hybridmail_event_123

32. Minimal API Surface

hybridmail-connect SHOULD expose a headless API.

32.1 Adapter Contract API

Required conceptual operations:

GET /adapter/descriptor
GET /adapter/health
POST /adapter/actions
POST /adapter/events/provider
GET /adapter/events
GET /adapter/letters/{id}/timeline
GET /adapter/letters/{id}/assessment

The actual transport may differ, but these conceptual operations should exist.

32.2 Standalone API

Useful standalone operations:

POST /hybridmail/letters
POST /hybridmail/batches
POST /hybridmail/letters/{id}/attachments
PUT /hybridmail/letters/{id}/options
POST /hybridmail/letters/{id}/preview
POST /hybridmail/letters/{id}/send
POST /hybridmail/letters/{id}/cancel
GET /hybridmail/letters/{id}
GET /hybridmail/letters/{id}/timeline
GET /hybridmail/letters/{id}/assessment
GET /hybridmail/letters/{id}/return-info
GET /hybridmail/letters/{id}/delivery-confirmation
GET /hybridmail/channel-health

33. Example End-to-End Flows

33.1 Ordinary Physical Letter

1. coordination-engine creates a coordination case.
2. A PDF payload is registered.
3. Policy selects hybrid mail as the delivery channel.
4. coordination-engine sends delivery.submit_letter to hybridmail-connect.
5. hybridmail-connect uploads the document to the provider.
6. Provider validates the document.
7. hybridmail-connect emits payload.validation_passed.
8. The letter is submitted for sending.
9. Provider transfers the letter for printing.
10. Print center hands the letter to the postal service.
11. hybridmail-connect emits delivery.postal.handed_over.
12. coordination-engine treats the participant as physically dispatched, but not necessarily as confirmed delivered unless policy accepts handover as sufficient.

33.2 Validation Failure and Correction

1. A PDF is uploaded.
2. Provider detects address-position or restricted-area issue.
3. hybridmail-connect emits payload.validation_failed with issue details.
4. coordination-engine marks the participant delivery attempt failed or action-required.
5. Policy requests correction, alternate document generation, or alternate channel.
6. Corrected payload is submitted with a new idempotency key or corrected version reference.

33.3 Registered Letter

1. A dunning letter is submitted with registered-mail option.
2. Provider validates and submits it.
3. Letter is handed to postal service.
4. Postal tracking events are received.
5. Delivery confirmation or return receipt event arrives.
6. hybridmail-connect emits delivery.postal.delivery_confirmed.
7. coordination-engine evaluates whether this satisfies the intended result.

33.4 Return Mail

1. Ordinary letter is handed to postal service.
2. No ordinary delivery confirmation is expected.
3. After several days or weeks, return mail is processed.
4. hybridmail-connect emits delivery.postal.return_received.
5. coordination-engine reopens, annotates, or fails the participant delivery state depending on policy.

33.5 Bulk Mailing

1. coordination-engine creates a batch delivery case.
2. hybridmail-connect submits a bulk/serial set of letters.
3. Some letters pass validation, others fail.
4. Per-letter evidence events are emitted.
5. coordination-engine aggregates participant states and avoids treating batch acceptance as universal success.

34. Provider Implementation Guidance

The first real provider flavor SHOULD be selected based on:

• API documentation availability
• upload and validation quality
• status granularity
• webhook support
• preview support
• return-mail support
• registered-letter support
• staging/sandbox support
• idempotency or duplicate prevention support
• cost and operational availability
• alignment with the first coordination scenario

The implementation SHOULD avoid hardcoding provider semantics into the core hybrid-mail model.

Implementation mapping should follow:

Provider API/status/webhook
→ hybridmail-native event
→ HybridmailEvidenceAssessment
→ EvidenceEvent for coordination-engine

35. Message Stream / Product Separation

hybridmail-connect SHOULD support separate configurations for different purposes.

Recommended streams:

transactional_letters
legal_or_high_assurance_letters
registered_letters
invoices
dunning
payroll
marketing_mailings
test

Steparation may affect:

• provider account
• sender identity
• billing account
• postal product
• print options
• return-mail handling
• retention policy
• production cutoff
• review/approval workflow
• evidence requirements

36. Legal and Compliance Disclaimer

hybridmail-connect does not by itself provide legal proof of notice, acceptance, signature, payment, or contract closure.

It provides evidence from the hybrid-mail production and postal dispatch chain.

Scenario-specific applications and coordination-engine policies may combine hybrid-mail evidence with registered-mail evidence, return-mail evidence, portal evidence, payment evidence, signature evidence, archive evidence, or manual evidence.

The adapter MUST avoid naming technical postal events in ways that imply legal success unless the event type is explicitly scoped.

Use:

delivery.postal.handed_over
delivery.postal.delivery_confirmed
delivery.postal.return_received

Avoid:

recipient_legally_notified
human_read_confirmed
contract_notice_completed

37. MVP Scope

The first useful version of hybridmail-connect should implement:

1. Adapter descriptor.
2. Provider flavor descriptor.
3. Adapter health endpoint.
4. delivery.submit_letter.
5. Idempotent submit request handling.
6. Simulated provider or one real provider flavor.
7. Letter, document, attempt, and recipient records.
8. Basic validation result mapping.
9. Basic print/shipping option mapping.
10. Basic status polling or webhook ingestion.
11. Evidence event generation.
12. Letter timeline.
13. Hybrid-mail evidence assessment.
14. Mapping to AdapterInterfaceSpecification.md v1.0.

MVP Required Hybrid-Mail Events

delivery.payload.submitted
delivery.payload.accepted
delivery.payload.rejected
payload.validation_passed
payload.validation_failed
delivery.payload.available
delivery.production.started
delivery.production.completed
delivery.postal.handed_over
delivery.postal.undeliverable
delivery.postal.return_received
delivery.postal.status_unknown
system.provider.degraded
system.provider.unavailable

MVP Acceptance Criteria

The MVP is acceptable when it can:

1. Accept a coordination-compatible hybrid-mail submit request.
2. Dispatch or simulate a PDF letter submission.
3. Preserve correlation and idempotency.
4. Prevent duplicate physical sends for duplicate idempotency keys.
5. Record provider acceptance separately from validation.
6. Classify validation failure as strong negative payload evidence.
7. Classify postal handover as strong dispatch evidence but not proof of human awareness.
8. Classify ordinary no-final-status cases as unresolved rather than success.
9. Record return mail as strong negative evidence.
10. Provide a letter timeline.
11. Provide a hybrid-mail evidence assessment.
12. Integrate with coordination-engine without overclaiming success.

38. Future Extensions

Potential future capabilities:

• multi-provider routing
• provider failover
• cost optimization by product/provider
• print-preview comparison
• PDF/A conversion support
• advanced address extraction
• address correction feedback loop
• return-mail scan ingestion
• registered-mail evidence archive
• delivery-confirmation document archive
• production SLA monitoring
• cutoff-aware scheduling
• country-specific postal product model
• automated correction workflows
• physical plus digital fallback patterns
• duplicate-content detection
• batch campaign analytics
• monthly journal / billing export integration
• print layout linting
• DIN 5008 address-window validation
• provider certification test suites

39. Non-Goals

hybridmail-connect is not:

• a document authoring system
• a PDF renderer by default
• a postal carrier
• a legal notice system by itself
• a signature system
• a payment system
• a CRM
• a full workflow engine
• the owner of coordination case success

It may integrate with such systems or be used by them.

40. Summary

hybridmail-connect models hybrid mail as a physical delivery channel initiated through digital submission.

Its job is to:

• submit PDF or print-ready documents
• validate hybrid-mail payloads
• map provider-specific print and shipping options
• track production and postal handover
• process return-mail and undeliverable evidence
• normalize registered or delivery-confirmation evidence
• expose document, letter, batch, and channel diagnostics
• integrate cleanly with coordination-engine

The key rule is:

Hybrid-mail events are physical production and postal-chain evidence, not automatic coordination result satisfaction. hybridmail-connect reports hybrid-mail facts and uncertainty. coordination-engine evaluates intended results.