coordination-engine/spec/HybridMailProviderApiComparison.md

HybridMailProviderApiComparison.md

1. Document Status

Document: HybridMailProviderApiComparison.md Project: hybridmail-connect Related Specifications:

• HybridmailAdapterSpecification.md
• HybridmailBinectSpecification.md
• HybridmailPingenSpecification.md
• HybridmailDpagSpecification.md
• AdapterInterfaceSpecification.md

Status: Draft v1.0 Scope: Provider API comparison, SWOT-style assessment, implementation implications, and coding-agent friendliness.

2. Purpose

This document compares three hybrid-mail provider APIs and provider-flavor candidates for hybridmail-connect:

• Binect
• Pingen
• Deutsche Post / E-POSTBUSINESS API / DPAG Hybrid Mail Shipments E-POST

The comparison focuses on their suitability as provider flavors for a generalized hybridmail-connect adapter that integrates with coordination-engine.

The goal is not to pick a single winner, but to understand:

• common baseline capabilities
• provider-specific strengths
• provider-specific risks and gaps
• evidence-model implications
• adapter implementation complexity
• coding-agent friendliness
• how public API digestability could be improved

3. Executive Summary

All three providers support the core hybrid-mail pattern:

digital document submission
→ provider-side validation / preparation
→ physical production
→ postal dispatch
→ status or delivery/return evidence where available

However, they differ in emphasis:

Provider	Strongest apparent API/product emphasis
Binect	Document-centric business-letter workflow with upload, attachments, preview, validation, sending, and status queries.
Pingen	Developer-friendly letter API with SDKs, idempotency, Track & Trace, webhooks, staging, send limits, and return-mail processing.
DPAG / E-POSTBUSINESS	Deutsche Post-native hybrid-mail infrastructure with PDF/PDF-A shipment submission, bulk upload, production data, shipment tracking, registered-mail use cases, positioning aids, cover sheets, and scheduled dispatch.

For hybridmail-connect, the best baseline design is a superset model with provider-specific capability descriptors. No provider flavor should be treated as the normative model. Instead, each provider should map into the generic lifecycle:

uploaded
accepted
validated
ready
submitted
processing
production_started
production_completed
postal_handover
in_transit
delivery_confirmed
undeliverable
return_received
status_unknown

The most important evidence principle remains:

Ordinary hybrid-mail APIs usually provide strong evidence of digital submission, validation, production, or postal dispatch. They do not automatically prove human awareness or legal receipt.

4. Source Basis and Confidence

This comparison is based on public provider information and public developer/API materials.

Binect

Public Binect API information confirms a REST/Swagger API for business-letter dispatch, document upload, attachments, print/shipping options, preview, sending, document status, shipping status, validation of address position/address format/restricted areas, and full-service print/enveloping/franking/dispatch. The public Swagger page exposes Binect API concepts and validation descriptions, while the Binect API page positions it as an integration API for document dispatch.

Pingen

Pingen publicly emphasizes a developer-friendly Letter API with SDKs for PHP, Python, Go, and .NET, Idempotency-Key support, rate limiting, configurable send limits, staging/sandbox, Track & Trace, webhooks, document validation, and return-mail processing. Pingen also documents detailed API status information and tracking “from A to Z.”

DPAG / E-POSTBUSINESS

Deutsche Post’s Hybrid Mail Shipments E-POST API documentation states that the E-POSTBUSINESS API expects single PDF documents for mail shipments, supports one-by-one and bulk upload, and provides detailed shipment processing information and bulk status requests. Deutsche Post’s business API material describes REST/Swagger documentation, shipment-level status with production data and shipment tracking, individual-to-mass submission, address-window positioning aids, automatic positioning, individual cover sheets, scheduled dispatch, and hybrid dispatch services.

Confidence Notes

The high-level comparison is reliable. Exact endpoint names, exact status names, native enum values, webhook payload shapes, product availability, account-specific capabilities, and cancellation behavior require validation against the live provider API documentation and target account configuration.

5. Common Baseline Across Providers

The shared baseline for hybridmail-connect should include:

document / PDF payload submission
provider-side acceptance
document validation
address / layout suitability checks
print and shipping options
sending / submission step
status polling or status retrieval
production / processing status
postal dispatch or handover evidence
return / undeliverable evidence where available
batch or serial processing where available
provider-specific status preservation

6. Core Differences at a Glance

Dimension	Binect	Pingen	DPAG / E-POSTBUSINESS
API style	REST/Swagger	Developer API with SDKs and docs	REST/Swagger API
Primary model	Document + sending	Letter + Track & Trace	PDF shipment / mail shipment
Public developer positioning	Business software / DMS / CRM integration	Strong developer friendliness	Partner/business software integration
Upload	Document upload	Letter/file creation	PDF shipment upload
Bulk / serial	Supported / relevant	Supported / relevant	One-by-one and bulk upload
Attachments	Publicly documented	Provider-specific	Provider-specific
Preview	Publicly documented	Likely / provider-specific	Provider-specific
Validation	Address position, address format, restricted areas	Document/letter validation	PDF/PDF-A, address-window, positioning, product/layout
Idempotency	Adapter-managed unless API support confirmed	Public Idempotency-Key support	Adapter-managed unless API support confirmed
Webhooks	Provider-specific / unclear publicly	Publicly documented webhook categories	Provider-specific / unclear publicly
Track & Trace	Status APIs	Strong public emphasis	Publicly documented shipment tracking / production data
Return mail	Provider-specific	Strong public emphasis	Product/provider-specific
Registered mail	Provider-specific	Supported/product-dependent	Publicly referenced
Delivery confirmation	Product-specific	Product-specific	Product-specific
Scheduled dispatch	Provider-specific	Provider-specific	Publicly referenced
Address positioning	Validation-oriented	Configurable address position	Positioning aids / automatic positioning
Cover sheets	Not public baseline	Provider-specific	Publicly referenced
Coding-agent friendliness	Medium	High	Medium

7. Provider-Specific Assessment: Binect

7.1 Binect Profile

Binect appears best modeled as a document-centric hybrid-mail provider.

The workflow centers on:

document upload
→ validation
→ optional attachments
→ print/shipping options
→ preview
→ sending
→ document/shipping status

Binect’s public API/Swagger documentation strongly supports the concept of document validation, including address-position, address-format, and restricted-area checks. It also supports attachments and preview retrieval, which makes it attractive for controlled document-dispatch workflows.

7.2 Binect Strengths

• Strong alignment with business-document dispatch.
• Public Swagger/API presence.
• Clear document upload and sending workflow.
• Public evidence of attachment handling.
• Public evidence of preview support.
• Validation concerns are visible and practically relevant.
• Suitable for DMS, CRM, and business-software integration.
• Likely a strong fit for Binect-owned or Binect-adjacent coordination scenarios.

7.3 Binect Weaknesses

• Public documentation is less marketing-developer-oriented than Pingen.
• Publicly available details about webhooks, idempotency, return mail, registered products, and delivery confirmation are less explicit.
• Exact native status model must be extracted from the live Swagger/API.
• Some concepts may require account-specific or product-specific configuration.
• Coding agents may need additional curated examples and mapping tables to avoid guessing.

7.4 Binect Opportunities

• Strong reference implementation for a German business-letter workflow.
• Good fit for coordination-engine scenarios involving document validation before dispatch.
• Attachments and preview support can support robust approval/review loops.
• Validation output can feed a postal-address-quality or document-layout-linting subsystem.
• Could become the first practical provider flavor if the user has strong domain access and Binect-specific knowledge.

7.5 Binect Threats / Risks

• If exact status semantics are not well documented, agents may over-map provider statuses to strong evidence.
• If idempotency is not native, duplicate physical sends must be prevented by the adapter.
• If webhooks are missing or not available, polling complexity increases.
• If return-mail and registered-letter semantics are not available through API, evidence strength remains limited for high-assurance scenarios.
• Provider-specific assumptions could leak into the generic HybridmailAdapterSpecification.md if not isolated.

7.6 Binect Implementation Priority

Recommended implementation priority:

1. Document upload
2. Validation mapping
3. Attachment upload
4. Print/shipping options
5. Preview retrieval
6. Send/submission
7. Status polling
8. Child/serial document status
9. Return/undeliverable mapping if available
10. Registered/delivery-confirmation mapping if available

8. Provider-Specific Assessment: Pingen

8.1 Pingen Profile

Pingen appears best modeled as a developer-friendly letter API with strong operational and integration features.

The workflow centers on:

letter/file creation
→ validation
→ auto-send or manual send
→ Track & Trace
→ webhooks
→ return-mail / undeliverable / delivered status categories

Pingen publicly emphasizes SDKs, Idempotency-Key headers, rate limiting, configurable send limits, staging/sandbox, Track & Trace, and webhooks. This makes it the most coding-agent-friendly provider in the comparison.

8.2 Pingen Strengths

• Strong developer positioning.
• Multi-language SDKs.
• Public idempotency support.
• Public rate-limit and send-limit support.
• Public staging/sandbox or full-feature simulation.
• Public Track & Trace emphasis.
• Public webhook categories.
• Strong return-mail processing story.
• Clear API-first product narrative.
• Excellent candidate for proving the generic hybridmail-connect adapter model.

8.3 Pingen Weaknesses

• Strong developer story does not remove the need to verify exact webhook payload semantics.
• “Delivered” terminology must be interpreted carefully and product-dependently.
• Some postal delivery confirmation semantics depend on selected products.
• Return-mail evidence can arrive late, requiring robust event-sourcing.
• Address-position and validation mapping must still be carefully normalized.

8.4 Pingen Opportunities

• Best candidate for an external reference provider flavor.
• Useful for validating webhook-first and polling-fallback architecture.
• Idempotency support can become the model for duplicate-send prevention.
• Track & Trace can help define the hybrid-mail timeline API.
• Staging/sandbox can support automated integration testing and coding-agent test loops.
• Return-mail processing can help define the negative-evidence model.

8.5 Pingen Threats / Risks

• Overinterpreting Track & Trace events as delivery confirmation.
• Treating “sent” as delivered.
• Treating product-specific delivered-letter events as generally available.
• Assuming webhook categories equal exact coordination event semantics without detailed payload mapping.
• Depending too heavily on SDK behavior rather than the underlying API contract.

8.6 Pingen Implementation Priority

Recommended implementation priority:

1. Authentication and workspace/account setup
2. Idempotent letter creation
3. Validation mapping
4. Auto-send/manual-send handling
5. Track & Trace polling
6. Webhook ingestion
7. Return-mail / undeliverable mapping
8. Delivered-letter mapping, product-dependent
9. Rate-limit/send-limit handling
10. Sandbox test harness

9. Provider-Specific Assessment: DPAG / E-POSTBUSINESS

9.1 DPAG Profile

DPAG / E-POSTBUSINESS appears best modeled as a postal-infrastructure-native hybrid-mail shipment API.

The workflow centers on:

PDF/PDF-A shipment upload
→ validation / positioning / cover-sheet handling
→ single or bulk submission
→ production data
→ shipment tracking
→ registered-mail / delivery-confirmation product evidence

The public Deutsche Post developer material explicitly describes single PDF documents, one-by-one and bulk upload, shipment processing information, bulk status requests, and tracking from uploading through delivery. Deutsche Post business API materials emphasize REST/Swagger, production data, shipment tracking, mass submission, address-window positioning aids, automatic positioning, individual cover sheets, and scheduled dispatch.

9.2 DPAG Strengths

• Direct connection to Deutsche Post hybrid-mail infrastructure.
• Strong postal-product alignment.
• Publicly documented PDF/PDF-A focus.
• Publicly documented bulk upload and bulk status.
• Publicly documented production data and shipment tracking.
• Publicly documented address-window positioning aids.
• Publicly documented automatic positioning and individual cover sheets.
• Publicly documented scheduled dispatch.
• Publicly referenced registered-letter use cases.
• Strong fit for German enterprise postal-delivery scenarios.

9.3 DPAG Weaknesses

• Adoption model appears more partner/business-software oriented.
• Exact active API access may require activation and credentials.
• Public material is less direct as a self-service developer experience than Pingen.
• Exact native status names and payloads need live API documentation.
• Exact idempotency behavior is unclear from public search result material.
• Exact webhook behavior is unclear from public search result material.
• Provider semantics may be more complex due to product diversity.

9.4 DPAG Opportunities

• Best candidate for postal-product completeness in the German market.
• Strong candidate for high-assurance physical dispatch scenarios.
• Registered-mail and shipment-tracking support can strengthen evidence models.
• Bulk upload/status can validate large-scale coordination cases.
• Address positioning and cover-sheet features can inform a powerful print-layout-validation subsystem.
• Scheduled dispatch can support deadline-aware coordination policies.

9.5 DPAG Threats / Risks

• Integration may be harder without partner activation or live account access.
• Coding agents may struggle if documentation is distributed across Swagger, PDFs, FAQs, and partner docs.
• Native status terminology may tempt overmapping to delivery_confirmed.
• Bulk status may be misread as per-recipient success unless child statuses are modeled.
• If idempotency is not native, duplicate physical shipment prevention must be adapter-managed.
• Product-specific registered-letter semantics must not be generalized.

9.6 DPAG Implementation Priority

Recommended implementation priority:

1. Authentication / activation model
2. Single PDF/PDF-A shipment upload
3. Validation and PDF/PDF-A issue mapping
4. Status polling
5. Production data mapping
6. Postal handover mapping
7. Bulk upload and bulk status
8. Address positioning / automatic positioning metadata
9. Cover-sheet support
10. Scheduled dispatch support
11. Registered-mail / delivery-confirmation mapping

10. SWOT Summary Matrix

10.1 Binect SWOT

Category	Assessment
Strengths	Document-centric workflow, attachments, preview, validation, business-software fit, Swagger/API visibility.
Weaknesses	Less explicit public detail on webhooks, idempotency, return mail, registered/delivery-confirmation semantics.
Opportunities	Strong Binect-specific implementation candidate, document validation as differentiator, good fit for DMS/CRM dispatch.
Threats	Risk of status overinterpretation, duplicate-send risk if no native idempotency, polling complexity, account-specific capability uncertainty.

10.2 Pingen SWOT

Category	Assessment
Strengths	Developer-friendly, SDKs, Idempotency-Key, rate limits, send limits, staging, Track & Trace, webhooks, return-mail processing.
Weaknesses	Exact delivered/return webhook semantics still require careful mapping; delivery confirmation is product-dependent.
Opportunities	Best external reference implementation, strong testability, strong coding-agent friendliness, good event-driven model.
Threats	Overinterpreting Track & Trace or delivered labels, relying too much on SDK abstraction, late return events changing assessments.

10.3 DPAG SWOT

Category	Assessment
Strengths	Postal-infrastructure-native, PDF/PDF-A focus, bulk upload/status, production data, shipment tracking, address positioning, cover sheets, scheduled dispatch, registered-mail use cases.
Weaknesses	More partner/account activation complexity, less self-service developer digestability, exact webhook/idempotency details unclear publicly.
Opportunities	Strongest postal-product depth, excellent for German enterprise and high-assurance physical dispatch, bulk and registered-mail patterns.
Threats	Documentation fragmentation, product-specific complexity, risk of overmapping status, harder test setup without active account.

11. Evidence Model Comparison

Evidence stage	Binect	Pingen	DPAG
Digital upload accepted	Yes	Yes	Yes
Validation passed/failed	Strong public evidence	Strong public evidence	Strong public evidence
Preview/review	Publicly visible	Provider-specific / likely	Provider-specific
Submitted for sending	Yes	Yes	Yes
Production status	Status-dependent	Track & Trace-dependent	Publicly emphasized production data
Postal handover	Status-dependent	Sent-letter / Track & Trace semantics	Shipment tracking / status semantics
Ordinary delivery confirmation	Not generally assumed	Not generally assumed	Not generally assumed
Product-specific delivery confirmation	Provider/account-specific	Product-dependent	Product-dependent / registered products
Return/undeliverable evidence	Provider-specific	Strong public feature	Product/provider-specific
Address correction evidence	Provider-specific	Provider-specific	Premiumadress / product-specific possibilities

12. Superset Baseline for hybridmail-connect

The provider comparison supports the following superset baseline:

supports_document_upload
supports_validation
supports_address_validation
supports_address_position_validation
supports_restricted_area_validation
supports_pdf_or_pdfa_validation
supports_print_options
supports_shipping_options
supports_preview
supports_single_letter
supports_bulk_or_serial_letters
supports_send_submission
supports_status_polling
supports_webhooks
supports_track_and_trace
supports_production_status
supports_postal_handover_status
supports_registered_mail
supports_delivery_confirmation
supports_return_mail
supports_address_correction
supports_scheduled_dispatch
supports_cover_sheet
supports_idempotency
supports_staging
supports_rate_limits
supports_send_limits

No flavor supports all of these equally. Therefore every provider flavor must declare capabilities explicitly.

13. Recommended Provider Flavor Strategy

13.1 Use Pingen as External Developer-Experience Reference

Pingen is the cleanest reference for:

idempotency
webhooks
Track & Trace
staging/sandbox
SDK examples
return-mail events
developer-facing onboarding

Pingen is likely the best provider to test the generic adapter event model from the outside because its public developer narrative is strongest.

13.2 Use Binect as Business-Document Workflow Reference

Binect is the best reference for:

document upload
attachments
print/shipping options
preview
business-software integration
address/layout validation

Binect is strategically important if coordination-engine is intended to support Binect-related products or partner scenarios.

13.3 Use DPAG as Postal-Depth Reference

DPAG is the best reference for:

postal-product richness
production data
shipment tracking
bulk upload/status
registered-mail variants
address positioning aids
automatic positioning
cover sheets
scheduled dispatch
German postal infrastructure alignment

DPAG is the strongest conceptual source for a complete German hybrid-mail standard, even if implementation may require more account and partner setup.

14. Implementation Complexity Assessment

Provider	Implementation complexity	Reason
Pingen	Medium	Strong docs/SDKs/idempotency/webhooks reduce integration complexity, but status semantics still require careful evidence mapping.
Binect	Medium to High	Workflow is clear but exact status/webhook/idempotency semantics likely need live Swagger/API and domain knowledge.
DPAG	High	Rich product set, partner activation, PDF/PDF-A, positioning, production data, tracking, bulk status, and product-specific semantics increase complexity.

15. Coding-Agent Friendliness

15.1 What Makes an API Coding-Agent Friendly?

An API is coding-agent friendly when a coding agent can reliably infer and implement correct behavior from its documentation without relying on undocumented assumptions.

Key properties:

machine-readable OpenAPI schema
stable endpoint semantics
complete enum documentation
clear lifecycle diagrams
exact state machine definitions
idempotency semantics
webhook schemas
error-code catalog
retry rules
sandbox/test environment
sample requests and responses
SDKs
typed schemas
provider-specific glossary
status-to-business-meaning warnings
capability descriptor
contract tests

15.2 Coding-Agent Friendliness Comparison

Dimension	Binect	Pingen	DPAG
Public developer positioning	Medium	High	Medium
Public Swagger/OpenAPI visibility	High	High / likely via docs	High
SDK availability	Not emphasized publicly	Strongly emphasized	Not primary public emphasis
Idempotency clarity	Unclear publicly	Strong	Unclear publicly
Webhook clarity	Unclear publicly	Strong	Unclear publicly
Sandbox/staging clarity	Unclear publicly	Strong	Present but activation/account-dependent
Status semantics digestability	Medium	Medium-High	Medium
Product semantics complexity	Medium	Medium	High
Agent implementation confidence from public docs alone	Medium	High	Medium-Low
Need for curated flavor spec	High	Medium	Very High

15.3 Pingen Coding-Agent Friendliness

Pingen is most coding-agent friendly because it publicly emphasizes:

• SDKs
• code examples
• developer-friendly documentation
• Idempotency-Key support
• rate limits
• send limits
• staging/sandbox
• Track & Trace
• webhooks

These are exactly the affordances coding agents need to produce reliable integrations.

Remaining improvements would include:

machine-readable event lifecycle schema
canonical webhook payload examples
explicit status-to-evidence mapping
clear statement of what "delivered" means per product
typed error-code catalog
contract-test suite

15.4 Binect Coding-Agent Friendliness

Binect has a public Swagger/API entry point and clearly relevant document workflow concepts. This is good for agents because the API is inspectable and operation-oriented.

However, coding-agent friendliness would improve significantly with:

explicit OpenAPI examples for every endpoint
published status enum table
published validation issue enum table
published webhook contract if webhooks exist
published idempotency policy
provider status lifecycle diagram
duplicate-send prevention guide
preview and attachment examples
serial/child document examples

Binect’s public documentation is enough for a strong conceptual provider flavor, but a coding agent implementing the adapter would benefit from curated mapping files generated from the live Swagger.

15.5 DPAG Coding-Agent Friendliness

DPAG has strong conceptual and product depth, and public material confirms REST/Swagger documentation and many important capabilities. However, the integration model appears more partner/account-activation oriented, and the relevant knowledge is spread across developer pages, business API pages, PDFs, FAQs, partner docs, and possibly active-account Swagger.

Coding-agent friendliness would improve significantly with:

single canonical OpenAPI bundle
machine-readable product capability matrix
complete status lifecycle map
PDF/PDF-A validation issue catalog
address-window positioning examples
automatic positioning examples
cover-sheet examples
bulk status examples
registered-mail event examples
delivery-confirmation semantics table
idempotency guidance
sandbox recipes
agent-readable "do not overclaim delivery" notes

DPAG is powerful but likely needs the most curation before coding agents can implement safely.

16. How API Digestability Could Be Improved

16.1 Provide Capability Descriptors

Every provider should expose a machine-readable capability descriptor.

Example:

provider: pingen
supports:
  webhooks: true
  idempotency: true
  return_mail: true
  delivery_confirmation: product_dependent
  registered_mail: true
  preview: true
  bulk: true
  staging: true

This avoids agent guesswork and makes provider flavor selection automatable.

16.2 Publish Explicit Lifecycle State Machines

Provider documentation should include lifecycle diagrams with exact state names.

Example:

created
→ uploaded
→ validation_pending
→ validation_passed
→ ready_for_sending
→ submitted
→ processing
→ handed_to_post
→ delivered | returned | unknown

Each state should declare:

meaning
terminal or non-terminal
retry behavior
whether it implies postal handover
whether it implies delivery confirmation
whether it is product-dependent

16.3 Separate Production, Postal Handover, and Delivery Confirmation

Hybrid-mail APIs should explicitly separate:

production_completed
postal_handover
postal_in_transit
delivery_confirmed
return_received

This is essential for coordination-engine because these states have different evidence grades.

16.4 Provide Status-to-Evidence Warnings

Each provider should document warnings such as:

"sent" means the letter entered the sending process, not that the recipient received it.
"handed over" means the postal carrier accepted the letter, not that the recipient read it.
"delivered" is only available for selected products and does not imply human awareness.

These warnings are critical for safe automation.

16.5 Publish Webhook Schemas and Examples

Webhook documentation should include:

event name
payload schema
example payload
retry behavior
signature verification
idempotency/deduplication key
event ordering assumptions
late event behavior
test-event endpoint

Pingen appears strongest here in public positioning, but all providers would benefit from standardized webhook docs.

16.6 Provide Idempotency Semantics

For hybrid mail, idempotency is not a convenience. It is a safety requirement.

Every provider should document:

which endpoints support idempotency keys
how long keys are retained
what constitutes a conflict
what happens after timeout
how duplicate sends are prevented
whether idempotency covers upload, send, or both

If provider-native idempotency is unavailable, adapter-managed idempotency must compensate.

16.7 Provide Validation Issue Catalogs

Validation errors should be machine-readable.

Useful fields:

issue_code
severity
category
page_number
bounding_box
fixable
human_message
machine_recommendation

This would greatly improve automated correction workflows.

16.8 Provide Sandbox and Golden Test Cases

Coding agents need reproducible fixtures.

Recommended test fixtures:

valid one-page domestic letter
valid multi-page duplex letter
invalid address position
restricted-area violation
invalid PDF
PDF/A issue
unsupported country
return-mail simulation
registered-mail delivered simulation
bulk partial-failure simulation
duplicate idempotency simulation

These would make adapter implementation much safer.

16.9 Provide OpenAPI Files Optimized for Code Generation

Provider OpenAPI documents should be:

complete
versioned
downloadable
validated
example-rich
schema-rich
enum-rich
error-rich
webhook-inclusive
security-scheme-explicit

A public Swagger UI is helpful, but agents benefit more from a downloadable OpenAPI file plus examples and contract tests.

17. Recommended Agent-Readable Provider Profile Format

Each provider flavor should maintain an agent-readable profile file.

Example:

provider: pingen
flavor_version: 1.0
contract_version: 1.0
confidence: public_docs_plus_live_api_required
capabilities:
  idempotency: true
  webhooks: true
  track_and_trace: true
  return_mail: true
  delivery_confirmation: product_dependent
status_mapping:
  sent:
    normalized_event: delivery.postal.handed_over
    confidence: medium
    warning: "Verify native semantics before enabling this mapping."
  delivered:
    normalized_event: delivery.postal.delivery_confirmed
    confidence: product_dependent
    warning: "Only for delivery-confirmation-capable product."
required_tests:
  - duplicate_send_prevention
  - validation_failure_mapping
  - return_mail_late_event
  - delivered_event_product_semantics

This would allow coding agents to implement providers without repeatedly re-reading large documents.

18. Recommended Implementation Order

18.1 For Proving the Generic Adapter

Use Pingen first if external provider access is easy.

Reason:

idempotency + webhooks + Track & Trace + staging + SDKs

make it a strong proving ground.

18.2 For Binect Strategic Fit

Use Binect first if the immediate business case is Binect-owned or Binect-integrated.

Reason:

document upload + attachments + preview + validation + business-letter dispatch

aligns strongly with Binect scenarios.

18.3 For Postal Completeness

Use DPAG early for conceptual completeness, but probably not as the first implementation unless account access and documentation are ready.

Reason:

product richness + bulk + production data + tracking + registered mail

make it strategically important but implementation-heavy.

19. Provider Flavor Risk Controls

Each provider flavor MUST include the following safety controls:

adapter-managed idempotency, even if provider idempotency exists
raw status preservation
conservative event mapping
product-specific delivery-confirmation mapping
batch child-status mapping
late return-event handling
explicit evidence grading
duplicate physical-send prevention
manual override support
provider capability descriptor

20. Recommended Hybrid-Mail Provider Abstraction

The comparison supports this provider abstraction:

HybridmailProviderFlavor
  capabilities
  document_model
  validation_model
  option_model
  send_model
  status_model
  tracking_model
  return_model
  delivery_confirmation_model
  evidence_mapping
  idempotency_model
  testing_model

This should become the internal structure of each provider flavor implementation.

21. Summary

Binect, Pingen, and DPAG all fit the hybridmail-connect model, but each contributes a different design center:

Binect = document workflow depth
Pingen = developer/API friendliness
DPAG = postal-product and infrastructure depth

For the framework, this is good news. The three providers collectively validate the need for a generic hybrid-mail adapter model with provider-specific flavors.

The most important implementation principle is:

Preserve provider-specific status detail, map conservatively to normalized evidence, and never turn physical dispatch terminology into coordination success without explicit product and policy support.

The most important improvement for coding-agent friendliness is:

Publish machine-readable capability descriptors, lifecycle state machines, status/evidence mapping tables, webhook schemas, validation catalogs, idempotency semantics, and golden test fixtures.