# 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```yaml 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: ```text created → uploaded → validation_pending → validation_passed → ready_for_sending → submitted → processing → handed_to_post → delivered | returned | unknown ``` Each state should declare: ```text 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: ```text 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: ```text "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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```yaml 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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.