Get Started
Learn what Paper Channel is and how it fits into the PagoPA notification platform.
Architecture
Understand the service architecture, components, and AWS integrations.
Quickstart
Set up a local development environment and send your first request.
API Reference
Explore the full internal and back-office API surface.
What is PN Paper Channel?
PN Paper Channel is a Spring Boot microservice within the PagoPA (Piattaforma Notifiche) ecosystem. It manages the full lifecycle of paper correspondence — registered mail and certified letters — sent to Italian citizens as legal notifications. The service handles:- Prepare phase — validates the delivery request, resolves recipient addresses via National Registries, and computes delivery costs based on active tender contracts
- Send phase — submits validated requests to External Channel for physical dispatch and registers the cost
- Event processing — consumes SQS events from postal operators, applies business rules per status code, and forwards progression events to Delivery Push
Paper Delivery Flow
Two-phase prepare/send lifecycle
Tenders & Costs
Procurement contracts and postal pricing
Queue Events
SQS-based status event processing
Address Resolution
Multi-step address lookup and fallback
Local Development
Run the service with LocalStack
Configuration
All application properties explained
Key capabilities
Asynchronous two-phase delivery
Asynchronous two-phase delivery
Delivery requests are split into a prepare step (address resolution, cost calculation) and a send step (submission to External Channel). This decoupling allows callers to validate and cost a request before committing to dispatch.
Tender-based cost management
Tender-based cost management
Postal costs are managed via procurement contracts (tenders) that define per-product, per-zone pricing with weight-based ranges. The back-office API and a dedicated Lambda function expose full CRUD operations for tender management.
Chained SQS event handlers
Chained SQS event handlers
Incoming delivery status codes (RECAG, RECRN, PNAG series) are processed by a chain of specialized message handlers. Each handler applies Italian postal regulation rules and delegates to downstream services such as Delivery Push and Safe Storage.
Encrypted address storage
Encrypted address storage
Recipient addresses are encrypted at rest using AWS KMS via the AWS Encryption SDK. Address de-anonymization is performed on-demand through the Data Vault microservice.
National Registry integration
National Registry integration
When a recipient address is not available, Paper Channel queries the National Registries service (ANPR/INA) to resolve the current physical address before attempting delivery.