coordination-engine/spec/HybridmailEpostbusinessSpecification.md

HybridmailDpagSpecification.md

1. Document Status

Document: HybridmailDpagSpecification.md Project: hybridmail-connect Provider Flavor: Deutsche Post / E-POSTBUSINESS API Parent Specification: HybridmailAdapterSpecification.md Target Integration: coordination-engine Adapter Contract: AdapterInterfaceSpecification.md v1.0 Status: Draft v1.0 Primary Scope: Deutsche Post / E-POSTBUSINESS hybrid-mail provider flavor for PDF mail-shipment submission, one-by-one and bulk upload, validation, address-window positioning, cover-sheet handling, scheduled dispatch, production status, shipment tracking, registered-mail products, and delivery/return evidence mapping.

2. Purpose

This document specifies the Deutsche Post / E-POSTBUSINESS API provider flavor for hybridmail-connect.

The DPAG flavor implements the generic hybrid-mail adapter model for the Deutsche Post E-POSTBUSINESS API / Deutsche Post Hybrid Mail Shipments E-POST API family. It maps Deutsche Post’s hybrid-mail API concepts into the provider-neutral hybrid-mail model used by coordination-engine.

The purpose of this document is to capture:

• DPAG/E-POSTBUSINESS-specific provider capabilities.
• DPAG-specific workflow stages.
• PDF mail-shipment submission.
• Single and bulk upload handling.
• Production and shipment-status mapping.
• Address-window positioning and automatic positioning semantics.
• Individual cover-sheet support where available.
• Scheduled dispatch semantics.
• Registered-mail and delivery-tracking semantics.
• PDF/PDF-A requirements and validation.
• DPAG-specific evidence event mapping.
• DPAG-specific limitations and assumptions.
• DPAG-specific MVP boundaries.

The DPAG flavor MUST remain compatible with HybridmailAdapterSpecification.md and MUST NOT leak DPAG-specific terminology into the core coordination model except through mapped provider metadata.

3. Grounding Summary

The public Deutsche Post / DHL developer and product material indicates the following relevant features:

• The Deutsche Post Hybrid Mail Shipments E-POST API is intended for business customers sending PDF documents as mail shipments with Deutsche Post.
• The API expects single PDF documents for mail shipments.
• It supports one-by-one and bulk upload.
• It provides detailed shipment processing information.
• It supports bulk status requests.
• It provides focused information for suppliers.
• It supports varied mail shipments of Deutsche Post with E-POST.
• It supports tracking the shipment from uploading through delivery.
• The broader E-POSTBUSINESS API is described as a REST API with Swagger documentation.
• It offers detailed shipment-level status information, including production data and shipment tracking.
• It supports individual submission through mass submission.
• It includes address-window positioning aids, automatic positioning, individual cover sheets, and scheduled dispatch.
• It includes hybrid dispatch services where digital documents are printed, enveloped, franked, and delivered as physical letters.
• Registered-letter use cases are part of the public API/product description.
• PDF/A-1b knowledge is explicitly relevant in public API notes.
• Activation, business-software partner setup, API access data, and technical login/access handling are part of the adoption model.

These facts define the baseline for this provider flavor.

4. Provider Flavor Identity

HybridmailProviderFlavorDescriptor:
  provider_name: dpag_epost
  provider_label: Deutsche Post E-POSTBUSINESS API / Hybrid Mail Shipments E-POST
  provider_family: hybridmail
  adapter_contract_version: "1.0"
  parent_specification: HybridmailAdapterSpecification.md
  deployment_mode: external

5. DPAG Capability Descriptor

The DPAG flavor MUST expose a capability descriptor.

HybridmailProviderFlavorDescriptor:
  provider_name: dpag_epost
  provider_version: provider_specific
  supported_file_types:
    - pdf
    - pdfa
  supported_attachment_file_types:
    - provider_specific
  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_bulk_status_requests: true
  supports_supplier_focused_status: true
  supports_registered_mail: true
  supports_delivery_confirmation: product_dependent
  supports_return_mail: provider_specific
  supports_address_correction: provider_specific
  supports_international_mail: true
  supports_cancellation: provider_specific
  supports_staging: true
  supports_idempotency: adapter_managed_or_provider_specific
  supports_rate_limits: true
  supports_scheduled_dispatch: true
  supports_address_window_positioning: true
  supports_automatic_positioning: true
  supports_cover_sheet: true
  supports_pdfa_validation: true
  supports_production_status: true
  supports_shipment_tracking: true
  supports_gogreen_plus: true
  supported_print_options:
    color_mode: provider_specific
    simplex_duplex: provider_specific
    envelope_selection: provider_specific
    address_position: true
    automatic_positioning: true
    cover_sheet: true
  supported_postal_products:
    - standard
    - registered
    - registered_return_receipt
    - delivery_confirmation
    - international
    - provider_specific
  limitations:
    - Public documentation confirms upload-to-delivery tracking, but exact native status names and semantics must be implemented against the active API documentation and account configuration.
    - Registered-mail and delivery-confirmation evidence are product-dependent.
    - Ordinary letters may provide strong production and postal-chain evidence without proving human awareness.
    - PDF/PDF-A and address-window constraints must be treated as provider-specific validation concerns.
    - Idempotency should be adapter-managed unless the active API endpoint provides native idempotency semantics.
    - Cancellation semantics are provider-specific and likely time-sensitive.

6. DPAG-Specific Conceptual Workflow

The DPAG flavor uses a PDF mail-shipment workflow.

authenticate / obtain access
→ prepare PDF or PDF/A document
→ submit single or bulk mail shipment
→ validate PDF, address, product, and layout constraints
→ optionally apply address-window positioning / automatic positioning / cover sheet
→ optionally schedule dispatch
→ provider accepts shipment
→ production processing
→ print / envelope / frank
→ postal handover
→ shipment tracking / registered-mail tracking where supported
→ delivery, return, or unknown final status depending on product and evidence

The adapter MUST preserve this distinction:

PDF upload is not validation success.
Validation success is not sending.
Sending/production is not postal handover.
Postal handover is not necessarily final delivery confirmation.
Delivery tracking is product- and status-dependent.

7. DPAG Object Mapping

7.1 Generic to DPAG Mapping

Generic hybrid-mail concept	DPAG flavor concept
HybridmailLetter	DPAG mail shipment / E-POST shipment
HybridmailDocumentRef	PDF/PDF-A document submitted for mail shipment
HybridmailAttempt	DPAG upload/submission/status operation
HybridmailBatch	Bulk upload / mass submission
PostalRecipient	Address extracted from PDF, positioned in address window, or provided through metadata where supported
HybridmailOptions	DPAG shipment, product, print, positioning, scheduling, and cover-sheet options
HybridmailPreview	Provider-specific preview or validation representation if supported
HybridmailTimeline	DPAG upload, production, shipment, tracking, and return timeline

7.2 DpagShipment

DpagShipment:
  dpag_shipment_id: string
  hybridmail_letter_id: string?
  coordination_case_id: string?
  participant_id: string?
  provider_status: string?
  normalized_status: string
  document_ref: DpagDocumentRef
  recipient: PostalRecipient?
  sender: PostalSender?
  options: DpagShipmentOptions?
  production_data_ref: string?
  tracking_ref: string?
  registered_mail_ref: string?
  created_at: timestamp
  updated_at: timestamp?
  metadata: object?

7.3 DpagDocumentRef

DpagDocumentRef:
  dpag_document_id: string?
  hybridmail_document_id: string
  original_file_ref: ResourceRef
  document_type: pdf | pdfa | unknown
  pdfa_profile: pdfa_1b | provider_specific | none | unknown
  file_size_bytes: integer?
  page_count: integer?
  sheet_count: integer?
  integrity_hash: string?
  validation_result: DpagValidationResult?
  created_at: timestamp
  metadata: object?

7.4 DpagSubmissionAttempt

DpagSubmissionAttempt:
  dpag_attempt_id: string
  hybridmail_letter_id: string?
  hybridmail_batch_id: string?
  provider_operation_id: string?
  idempotency_key: string
  operation_type: upload_single | upload_bulk | validate | submit | status_poll | bulk_status_poll | cancel | tracking_poll
  state: pending | accepted | rejected | failed | completed | duplicate | unknown
  created_at: timestamp
  updated_at: timestamp?
  raw_provider_response_ref: string?

7.5 DpagBatch

DpagBatch:
  dpag_batch_id: string?
  hybridmail_batch_id: string
  coordination_case_id: string?
  batch_type: bulk | mass_submission | serial | mixed | unknown
  shipments:
    - dpag_shipment_id
  state: pending | partial | completed | failed | unknown
  created_at: timestamp
  updated_at: timestamp?
  bulk_status_ref: string?

Batch-level status MUST NOT be treated as success for every child shipment unless DPAG status data provides per-shipment evidence or scenario policy explicitly accepts batch-level evidence.

8. DPAG Address and Positioning Model

Public material explicitly mentions address-window positioning aids and automatic positioning. The DPAG flavor MUST model address positioning as a first-class provider concern.

DpagAddressPositioning:
  mode: fixed_window | automatic_positioning | cover_sheet | metadata | provider_default | unknown
  window_position: left | right | provider_specific | unknown
  page_number: integer?
  bounding_box: object?
  provider_positioning_result: string?
  confidence: low | medium | high

Generic postal recipient mapping:

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 | cover_sheet | manual | unknown
  address_quality: PostalAddressQuality?

If automatic positioning or cover-sheet generation changes where the address appears in the physical output, the adapter MUST preserve that fact in metadata.

9. DPAG Cover Sheet Model

Public material references individual cover sheets. The adapter SHOULD model cover-sheet use explicitly.

DpagCoverSheet:
  enabled: boolean
  cover_sheet_type: individual | provider_default | provider_specific | unknown
  recipient_source: metadata | extracted | provided | unknown
  sender_source: metadata | provided | provider_default | unknown
  template_ref: string?
  generated_document_ref: ResourceRef?
  metadata: object?

Cover-sheet generation is a production preparation step. It does not prove physical dispatch.

10. DPAG Scheduled Dispatch Model

Public material references scheduled dispatch. The adapter SHOULD model dispatch timing.

DpagScheduledDispatch:
  dispatch_mode: immediate | scheduled | provider_default | unknown
  desired_dispatch_date: date?
  desired_dispatch_time_window: string?
  schedule_status: not_scheduled | scheduled | missed | cancelled | completed | unknown
  metadata: object?

Scheduled dispatch affects policy interpretation:

A letter scheduled for future dispatch should remain pending until the scheduled production/dispatch window begins.

11. DPAG Shipment Options

The DPAG flavor MUST map DPAG options into generic HybridmailOptions.

DpagShipmentOptions:
  color_mode: color | grayscale | provider_default | unknown
  print_sides: simplex | duplex | provider_default | unknown
  envelope_type: c5 | c4 | window_left | window_right | provider_default | unknown
  address_positioning: DpagAddressPositioning?
  cover_sheet: DpagCoverSheet?
  postage_product: standard | registered | registered_return_receipt | delivery_confirmation | international | provider_specific
  country_scope: domestic | international | unknown
  scheduled_dispatch: DpagScheduledDispatch?
  return_mail_handling: none | provider_processed | physical_return | digital_return_info | unknown
  gogreen_plus: boolean?
  metadata: object?

Provider-native option names MUST be preserved in metadata.

The adapter MUST NOT assume support for a product unless the DPAG capability descriptor confirms it for the active account/API context.

12. DPAG Validation Model

DPAG validation results MUST be mapped into generic HybridmailValidationResult.

DpagValidationResult:
  dpag_shipment_id: string?
  dpag_document_id: string?
  provider_validation_state: string?
  validation_state: pending | passed | action_required | failed | unknown
  issues:
    - DpagValidationIssue
  validated_at: timestamp?
  raw_provider_response_ref: string?

DpagValidationIssue:
  provider_issue_code: string?
  issue_code: string
  severity: info | warning | action_required | fatal
  category: format | pdf | pdfa | page_size | address | address_position | restricted_area | cover_sheet | margins | file_size | page_count | postage | country | scheduled_dispatch | provider_policy | unknown
  message: string
  page_number: integer?
  bounding_box: object?
  fixable: boolean?

13. DPAG Validation Issue Mapping

DPAG validation concern	Generic validation category	Normalized issue code
Invalid PDF	pdf / format	invalid_pdf
PDF/A-1b issue	pdfa	invalid_pdfa_1b
Unsupported file type	format	unsupported_file_type
Page or file constraint violated	page_count / file_size	document_constraint_violation
Address not detected	address	address_not_detected
Address-window problem	address_position	address_position_invalid
Automatic positioning failed	address_position	automatic_positioning_failed
Cover sheet generation failed	cover_sheet	cover_sheet_failed
Restricted-area or margin violation	restricted_area / margins	layout_restricted_area_violation
Unsupported destination country	country	unsupported_country
Postal product invalid	postage	unsupported_product
Scheduled dispatch invalid	scheduled_dispatch	scheduled_dispatch_invalid
Provider policy rejection	provider_policy	provider_policy_rejected
Unknown validation issue	unknown	unknown_validation_issue

Validation failure MUST emit:

payload.validation_failed

Validation success MUST emit:

payload.validation_passed

Warnings MAY allow processing to continue, but the warning MUST be preserved in metadata.

14. DPAG Status Model

The DPAG flavor MUST preserve raw provider status and map it to normalized status.

DpagStatusRecord:
  status_record_id: string
  dpag_shipment_id: string?
  dpag_batch_id: string?
  provider_status: string
  normalized_status: string
  status_scope: upload | validation | production | shipment | tracking | registered_mail | bulk | supplier | unknown
  observed_at: timestamp
  raw_provider_response_ref: string?

15. Normalized DPAG Status Categories

The DPAG flavor SHOULD map native statuses into these normalized categories:

shipment.created
shipment.uploaded
shipment.validation_pending
shipment.validation_passed
shipment.validation_failed
shipment.action_required
shipment.ready_for_sending
shipment.scheduled
shipment.submitted_for_sending
shipment.processing
shipment.production_started
shipment.production_completed
shipment.handed_to_postal_service
shipment.in_transit
shipment.delivery_confirmed
shipment.registered_event
shipment.undeliverable
shipment.return_received
shipment.cancelled
shipment.failed
shipment.status_unknown

Where DPAG status granularity is insufficient, the adapter MUST use the nearest weaker event and preserve raw status in metadata.

16. DPAG Production Data Model

Public documentation references production data. The adapter SHOULD model production-stage evidence separately from postal-stage evidence.

DpagProductionData:
  dpag_shipment_id: string
  production_status: pending | started | completed | failed | unknown
  print_status: pending | printed | failed | unknown
  enveloping_status: pending | enveloped | failed | unknown
  franking_status: pending | franked | failed | unknown
  production_site_ref: string?
  production_started_at: timestamp?
  production_completed_at: timestamp?
  raw_provider_response_ref: string?

Production completion does not prove postal handover unless the provider status explicitly supports that interpretation.

17. DPAG Tracking Model

Public documentation references shipment tracking from upload through delivery. The adapter SHOULD model tracking as a separate status stream.

DpagTrackingEvent:
  tracking_event_id: string
  dpag_shipment_id: string
  provider_tracking_id: string?
  tracking_type: production | postal | registered_mail | delivery_confirmation | return | unknown
  provider_status: string
  normalized_status: string
  occurred_at: timestamp?
  observed_at: timestamp
  raw_provider_response_ref: string?
  metadata: object?

Tracking events MUST be mapped according to their actual semantics.

For ordinary mail, a tracking stage may indicate process progress without proving delivery.

For registered mail or delivery-confirmation products, tracking events may provide stronger physical-delivery evidence.

18. DPAG Registered Mail Model

The public API material references registered-letter use cases and varied mail shipments.

DpagRegisteredMail:
  dpag_shipment_id: string
  registered_product_type: registered | registered_return_receipt | delivery_confirmation | provider_specific
  registered_tracking_id: string?
  status: created | in_transit | delivery_attempted | delivered | refused | returned | undeliverable | unknown
  delivery_confirmation_ref: ResourceRef?
  recipient_signature_ref: ResourceRef?
  occurred_at: timestamp?
  observed_at: timestamp?
  raw_provider_response_ref: string?

The adapter MUST only emit:

delivery.postal.delivery_confirmed

when the DPAG status and selected postal product semantically support delivery confirmation.

Ordinary letter dispatch MUST NOT be mapped to delivery.postal.delivery_confirmed.

19. DPAG Bulk Status Model

The API supports bulk upload and bulk status requests. The adapter MUST support per-shipment state under a batch.

DpagBulkStatus:
  dpag_batch_id: string
  status_observed_at: timestamp
  batch_status: pending | partial | completed | failed | unknown
  child_statuses:
    - DpagChildShipmentStatus
  raw_provider_response_ref: string?

DpagChildShipmentStatus:
  dpag_batch_id: string
  dpag_shipment_id: string
  hybridmail_letter_id: string?
  participant_id: string?
  provider_status: string
  normalized_status: string
  evidence_event_refs:
    - string
  updated_at: timestamp?
  metadata: object?

Batch-level acceptance MUST NOT be treated as per-recipient success without child-shipment evidence.

20. DPAG-to-Generic Event Mapping

DPAG workflow event	Generic event	Evidence interpretation
PDF upload accepted	delivery.payload.accepted	Digital submission accepted
PDF upload rejected	delivery.payload.rejected	Attempt failed
Validation passed	payload.validation_passed	Document is provider-processable
Validation failed	payload.validation_failed	Document/action must be corrected
Automatic positioning applied	delivery.payload.available with positioning metadata	Operational readiness, not dispatch
Cover sheet generated	delivery.payload.available with cover-sheet metadata	Operational readiness
Scheduled dispatch accepted	delivery.payload.available with schedule metadata	Future dispatch pending
Submitted for sending	delivery.payload.submitted	Provider instructed to send
Production started	delivery.production.started	Provider production began
Production completed	delivery.production.completed	Physical production completed
Handed to postal service	delivery.postal.handed_over	Strong dispatch evidence
Tracking in transit	delivery.postal.in_transit	Postal tracking evidence
Registered tracking event	delivery.postal.in_transit or delivery.postal.delivery_confirmed depending status	Product-dependent
Delivery confirmed	delivery.postal.delivery_confirmed	Strong physical-delivery evidence
Undeliverable	delivery.postal.undeliverable	Strong negative delivery evidence
Return received	delivery.postal.return_received	Strong negative evidence
Bulk status child failed	child-level event	Per-recipient failure
Bulk status child completed	child-level mapped event	Per-recipient progress

21. Evidence Grading Rules

21.1 DPAG PDF 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:
  - DPAG accepted the digital PDF upload into the API workflow.
  - This does not prove validation, production, postal handover, or delivery.

21.2 DPAG 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:
  - DPAG validation passed or the shipment is processable according to provider status.
  - This does not prove sending or postal handover.

21.3 DPAG 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:
  - DPAG reported a document, address, layout, PDF/PDF-A, product, or policy issue.
  - The issue should be categorized and preserved.

21.4 DPAG Production Started

event_type: delivery.production.started
evidence_grade:
  strength: medium
  actor_certainty: none
  authority_certainty: none
  payload_certainty: high
  interaction_certainty: none
  timing_certainty: medium
  channel_certainty: high
  non_repudiation_strength: low
notes:
  - DPAG status indicates production processing started.
  - The exact native status should be preserved in metadata.

21.5 DPAG Production Completed

event_type: delivery.production.completed
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:
  - DPAG production status indicates physical production completed.
  - This does not prove postal handover unless the provider status explicitly says so.

21.6 DPAG Postal Handover

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:
  - DPAG status indicates handover into the physical postal delivery chain.
  - This is strong dispatch evidence.
  - It does not prove recipient receipt or reading.

21.7 DPAG 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:
  - DPAG registered-mail or delivery-confirmation evidence indicates physical delivery.
  - Product and native status semantics must support this mapping.
  - This may still not prove that the intended human personally read the payload.

21.8 DPAG Undeliverable / Return

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:
  - DPAG or postal-chain status indicates undeliverable or returned mail.
  - This is strong negative evidence for the physical delivery attempt.

22. DPAG Evidence Assessment

The DPAG flavor SHOULD provide a DPAG-native evidence assessment.

DpagEvidenceAssessment:
  hybridmail_letter_id: string
  dpag_shipment_id: string?
  dpag_batch_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?

22.1 DPAG Adapter Success Subclasses

success.pdf_uploaded
success.validation_passed
success.positioning_applied
success.cover_sheet_generated
success.scheduled_dispatch_accepted
success.submitted_for_sending
success.production_started
success.production_completed
success.handed_to_postal_service
success.registered_tracking_event
success.delivery_confirmed
success.return_info_processed

22.2 DPAG Adapter Fail Subclasses

fail.upload_rejected
fail.validation_failed
fail.invalid_pdf
fail.invalid_pdfa
fail.address_position_invalid
fail.automatic_positioning_failed
fail.cover_sheet_failed
fail.address_invalid
fail.unsupported_country
fail.unsupported_product
fail.scheduled_dispatch_invalid
fail.provider_rejected
fail.production_failed
fail.cancelled
fail.undeliverable
fail.return_received

22.3 DPAG Adapter Undef Subclasses

undef.pending
undef.uploaded_only
undef.validation_pending
undef.action_required
undef.ready_but_not_sent
undef.scheduled_for_future_dispatch
undef.submitted_for_sending
undef.processing
undef.production_status_unknown
undef.production_completed_but_handover_unproven
undef.handed_to_postal_service_but_delivery_unproven
undef.tracking_pending
undef.registered_tracking_pending
undef.no_final_status_expected
undef.bulk_status_partial
undef.conflicting_evidence
undef.channel_degraded

23. DPAG Workflow States

The DPAG flavor SHOULD support these normalized workflow states:

created
upload_requested
uploaded
upload_failed
validation_pending
validation_passed
validation_failed
action_required
positioning_pending
positioning_applied
positioning_failed
cover_sheet_pending
cover_sheet_generated
cover_sheet_failed
ready_for_sending
scheduled
send_requested
submitted_for_sending
processing
production_started
production_completed
handed_to_postal_service
in_transit
registered_event
delivery_confirmed
undeliverable
return_received
cancelled
failed
unknown

These are DPAG-flavor states, not coordination result states.

24. DPAG Idempotency and Duplicate Send Prevention

Duplicate physical send prevention is mandatory.

If the DPAG endpoint used does not provide native idempotency, hybridmail-connect MUST implement adapter-managed idempotency.

Idempotency scope SHOULD include:

coordination_case_id
participant_id
delivery_id
payload_id
payload_integrity_hash
provider_flavor
postal recipient
shipment options
scheduled dispatch date
postal product

A repeated delivery.submit_letter request with the same idempotency key MUST NOT create a second physical shipment.

If the repeated request refers to a changed payload, changed address, changed schedule, or changed product, the adapter MUST reject it as an idempotency conflict unless a new idempotency key is provided.

25. DPAG Authentication and Access Handling

The DPAG flavor SHOULD model authentication separately from business events.

Public material indicates activation/API access and technical login/access handling are relevant.

DpagAuthContext:
  api_account_ref: string
  technical_login_ref: string?
  token_ref: string?
  authentication_mode: oauth2 | technical_login | api_key | provider_specific | unknown
  token_expires_at: timestamp?
  activation_state: not_activated | activated | suspended | unknown

Authentication failures SHOULD map to:

system.provider.unavailable
notification/delivery action error with category: authentication

unless the provider returns a business-level rejection for the submitted shipment.

26. DPAG Status Polling and Webhooks

The DPAG flavor MUST support polling if the API exposes status retrieval.

The DPAG flavor MAY support webhooks if available in the active provider setup.

DpagStatusPollingConfig:
  enabled: boolean
  initial_delay_seconds: integer
  interval_seconds: integer
  max_duration_seconds: integer
  supports_bulk_status: boolean
  supports_tracking_status: boolean
  terminal_statuses:
    - delivery_confirmed
    - handed_to_postal_service
    - undeliverable
    - returned
    - failed
    - cancelled

Polling MUST preserve status history and MUST NOT overwrite raw evidence.

27. DPAG Raw Event Preservation

The DPAG flavor SHOULD preserve raw provider responses or references to them.

RawDpagEventRef:
  raw_event_id: string
  source: api_response | status_poll | bulk_status_poll | tracking_poll | webhook | validation | production_data | operator
  endpoint: string?
  storage_ref: string?
  received_at: timestamp
  redacted: boolean

Normalized events SHOULD reference raw DPAG event data where available.

28. DPAG Channel Health

DpagChannelHealth:
  provider_name: dpag_epost
  provider_account_ref: string?
  status: healthy | degraded | failing | unknown
  activation_status: activated | not_activated | suspended | 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
  status_api_status: healthy | degraded | unavailable | unknown
  tracking_status: healthy | degraded | unavailable | product_dependent | unknown
  bulk_status_api_status: healthy | degraded | unavailable | unknown
  cutoff_status: before_cutoff | after_cutoff | no_production_day | unknown
  known_degradations:
    - string

Health events SHOULD map to:

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

29. Security Requirements

The DPAG flavor MUST:

• protect DPAG API credentials and technical login data.
• use secure transport.
• avoid logging document contents.
• protect postal recipient data.
• preserve idempotency.
• prevent duplicate physical shipments.
• separate test/sandbox and production configuration.
• protect tracking and status data.
• validate file type and size before upload where possible.
• protect generated cover sheets and derived print artifacts.
• apply tenant/account separation where applicable.

30. Privacy Requirements

The DPAG flavor SHOULD:

• store payload references instead of payload content where possible.
• support metadata-only mode after provider submission.
• mask postal address data in logs.
• support configurable retention of raw provider responses.
• support configurable retention of generated cover sheets and artifacts.
• separate operational diagnostics from coordination evidence.
• document provider-side retention limitations.
• support deletion or anonymization workflows where legally possible.

31. Reliability Requirements

The DPAG flavor MUST support:

• idempotent upload and send requests.
• duplicate status event detection.
• out-of-order status handling.
• polling-based status recovery.
• bulk status retrieval and partial-state handling.
• late tracking events.
• late return/undeliverable events.
• retryable upload failures.
• non-retryable validation failures.
• provider timeout handling.
• validation issue preservation.
• tracking history preservation.
• correlation preservation.
• dead-letter handling for unprocessable provider responses.

32. Minimal API Surface

The DPAG flavor SHOULD implement or expose these conceptual operations through hybridmail-connect.

32.1 Adapter Contract 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

32.2 DPAG Flavor Operations

POST /dpag/shipments
POST /dpag/shipments/bulk
POST /dpag/shipments/{id}/validate
POST /dpag/shipments/{id}/send
POST /dpag/shipments/{id}/cancel
GET /dpag/shipments/{id}
GET /dpag/shipments/{id}/status
GET /dpag/shipments/{id}/tracking
GET /dpag/shipments/bulk/{batch_id}/status
GET /dpag/shipments/{id}/timeline
GET /dpag/shipments/{id}/assessment
GET /dpag/channel-health

The exact provider endpoint names MUST be implemented according to the live DPAG/E-POSTBUSINESS API documentation. The conceptual operations above define the adapter-facing semantic model.

33. Example End-to-End Flow

33.1 Single DPAG Hybrid-Mail Shipment

1. coordination-engine creates a coordination case.
2. A PDF or PDF/A payload is registered.
3. Policy selects hybridmail-connect with provider flavor dpag_epost.
4. coordination-engine sends delivery.submit_letter.
5. hybridmail-connect submits the PDF to DPAG.
6. DPAG accepts the submission.
7. The adapter emits delivery.payload.accepted.
8. DPAG validation/status indicates the shipment is processable.
9. The adapter emits payload.validation_passed.
10. If address-window positioning, automatic positioning, or cover-sheet generation is used, the adapter records the result as operational metadata.
11. The shipment is submitted or scheduled for sending.
12. The adapter emits delivery.payload.submitted.
13. Production data indicates processing/production.
14. The adapter emits delivery.production.started and later delivery.production.completed if semantically supported.
15. DPAG status indicates handover to the postal chain.
16. The adapter emits delivery.postal.handed_over.
17. coordination-engine evaluates whether postal handover is sufficient for the case policy.

33.2 Validation Failure

1. DPAG rejects or flags the PDF due to PDF/PDF-A, address-window, cover-sheet, product, or layout issue.
2. The adapter emits payload.validation_failed.
3. The validation issue is preserved with category and severity.
4. coordination-engine marks the participant delivery as action-required or failed for this attempt.
5. Policy requests document correction, alternate generation, or fallback channel.

33.3 Scheduled Dispatch

1. coordination-engine submits a shipment with a desired dispatch date.
2. DPAG accepts the schedule.
3. The adapter records scheduled_dispatch.
4. Participant remains undef.scheduled_for_future_dispatch.
5. When the dispatch window begins and DPAG status progresses, the adapter emits production and postal events.
6. coordination-engine derives updated participant state.

33.4 Registered Letter

1. A shipment is submitted with a registered-mail product.
2. DPAG accepts and processes the shipment.
3. Registered tracking events are received.
4. The adapter emits delivery.postal.in_transit for intermediate tracking events.
5. If a delivery-confirming status is received, the adapter emits delivery.postal.delivery_confirmed.
6. coordination-engine evaluates whether this satisfies the intended result.

33.5 Bulk Shipment

1. coordination-engine creates a batch delivery case.
2. hybridmail-connect submits a bulk upload to DPAG.
3. DPAG returns batch and per-shipment status data.
4. The adapter records DpagBulkStatus and DpagChildShipmentStatus.
5. The adapter emits per-child evidence events.
6. coordination-engine aggregates participant-level states and does not treat batch acceptance as universal success.

34. DPAG MVP Scope

The first DPAG flavor implementation should include:

1. DPAG provider flavor descriptor.
2. Adapter descriptor integration.
3. DPAG credential/config handling.
4. Single PDF/PDF-A shipment submission.
5. Bulk shipment submission model, at least simulated or structurally supported.
6. Validation result mapping.
7. Address-window / positioning metadata handling.
8. Scheduled dispatch metadata handling.
9. Sending submission.
10. Status polling.
11. Bulk status polling where available.
12. Production status mapping.
13. Shipment tracking mapping.
14. Registered-mail status mapping where product-supported.
15. Evidence event generation.
16. Shipment timeline.
17. DPAG evidence assessment.
18. Adapter-managed idempotency unless provider endpoint support is verified.

MVP Required DPAG Events

delivery.payload.accepted
delivery.payload.rejected
payload.validation_passed
payload.validation_failed
delivery.payload.available
delivery.payload.submitted
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.status_unknown
system.provider.degraded
system.provider.unavailable

Where a provider status is unavailable or semantically unclear, the adapter MUST emit the weakest safe event and preserve the raw status.

35. DPAG MVP Acceptance Criteria

The DPAG flavor MVP is acceptable when it can:

1. Accept a coordination-compatible delivery.submit_letter request.
2. Upload or simulate upload of a PDF/PDF-A DPAG shipment.
3. Preserve correlation and idempotency.
4. Prevent duplicate physical shipments for duplicate idempotency keys.
5. Map upload acceptance to delivery.payload.accepted.
6. Map validation success to payload.validation_passed.
7. Map PDF/PDF-A, address-window, or layout validation failure to payload.validation_failed.
8. Map send submission to delivery.payload.submitted.
9. Map production status to delivery.production.started or delivery.production.completed only when supported by native status semantics.
10. Map postal handover only when semantically supported by provider status.
11. Map delivery confirmation only when the selected product/status supports it.
12. Map bulk child statuses per shipment where available.
13. Provide a DPAG shipment timeline.
14. Provide a DPAG evidence assessment.
15. Integrate with coordination-engine without overclaiming physical delivery or human awareness.

36. Open Questions

1. Which exact DPAG native statuses map to delivery.production.started, delivery.production.completed, delivery.postal.handed_over, and delivery.postal.delivery_confirmed?
2. Which endpoint names and payload fields are present in the active E-POSTBUSINESS API version used by the target account?
3. Does the target DPAG account/API configuration expose webhooks, or is polling the required baseline?
4. Which registered-mail and delivery-confirmation products are available in the target account?
5. Which PDF/A constraints are enforced automatically and which are documented as implementer responsibility?
6. Which address-window positioning modes are available in the active API?
7. How are individual cover sheets represented in the API?
8. How is scheduled dispatch represented and how are missed schedules surfaced?
9. Which bulk status fields provide child-shipment identity and per-recipient status?
10. Should DPAG validation issues update a shared postal address quality registry?
11. Does the active API provide native idempotency, or must idempotency remain fully adapter-managed?
12. Which GoGreen Plus or sustainability metadata should be captured for reporting?

37. Non-Goals

The DPAG flavor is not:

• a document authoring system.
• a PDF renderer by default.
• a legal notice system by itself.
• a postal carrier abstraction for all DPAG products.
• a general E-POST UI replacement.
• the owner of coordination case success.
• the owner of contract, payment, or signature result semantics.

It integrates DPAG/E-POSTBUSINESS hybrid-mail capabilities into the coordination framework.

38. Summary

HybridmailDpagSpecification.md defines the DPAG/E-POSTBUSINESS provider flavor for hybridmail-connect.

The DPAG flavor models Deutsche Post hybrid-mail shipment as a PDF-centered physical-mail dispatch channel with:

• PDF/PDF-A shipment submission
• one-by-one and bulk upload
• validation
• address-window positioning aids
• automatic positioning
• individual cover sheets
• scheduled dispatch
• production data
• shipment tracking
• registered-mail / delivery-confirmation products where supported
• bulk and per-shipment status
• postal handover and return/undeliverable evidence

The key rule is:

DPAG/E-POSTBUSINESS events are provider, production, postal-chain, shipment-tracking, and registered-mail evidence. They are not automatic coordination result satisfaction. hybridmail-connect reports DPAG-channel facts and uncertainty. coordination-engine evaluates intended results.