generated from coulomb/repo-seed
926 lines
38 KiB
Markdown
926 lines
38 KiB
Markdown
# 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.
|
||
|