Mailpiece

States

We originally modelled mailpiece states on the Stannp API (our first printer integration). They are as follows:

graph LR
Submitted --> Received
Received --> Producing
Producing --> HandedOver
HandedOver --> InTransit
InTransit --> LocalDelivery
LocalDelivery --> Delivered
Delivered --> Returned
Returned --> Cancelled
Test
Error
Sent
Processed
Unknown --- UnknownDescription[Default value used when an invalid one is provided]

classDef starting fill:#96d0ff;
classDef ending fill:#ffd6d6;
classDef static fill:#dccbff;

class Submitted starting;
class Delivered ending;
class Returned ending;
class Cancelled ending;
class Test static;

When we use a printer other than Stannp, we receive their state data in their webhooks and update our Mailpiece model state. The mappings for each are below.

Submitted

All postcards start in this state. We don't map printer states since this is just what we use when we've sent it to them.

Received

• Intelliprint
  • waiting_to_print

Producing

• LOB
  • postcard.created

HandedOver

• LOB
  • postcard.mailed
• Taylor
  • 11

InTransit

• LOB
  • postcard.in_transit

LocalDelivery

• LOB
  • postcard.processed_for_delivery
  • postcard.in_local_area

Delivered

• LOB
  • postcard.delivered
• Taylor
  • 12
• Intelliprint

Returned

• LOB
  • postcard.returned_to_sender

Cancelled

• LOB
  • postcard.deleted
• Intelliprint
  • invalid_address

Test

Error

• Taylor
  • -1
• Intelliprint
  • invalid_address
  • failed

Sent

• Intelliprint
  • rendered

Processed

• Taylor
  • 9
  • 10

Unknown

Webhook flow

1. Printer sends webhook → routes/webhook_routes.py
2. enqueue_mail_status_webhook() → SQS queue
3. process_status_updates() dequeues every 15s → celery/mail_statuses.py
4. parse_status_update_from_sqs_response() converts printer status → MailpieceStatus
5. update_mailpiece_statuses() bulk updates database

Key files

• Model: core/models/mailpieces.py, core/models/mailpiece_status.py
• Conversion: core/integrations/printers/status_conversion.py
• Processing: celery/mail_statuses.py, methods/mailpieces.py
• Creation: methods/runner.py (sets Submitted or Error)