pyimb

A Python library for encoding and decoding USPS Intelligent Mail Barcodes (IMb).

About This Project

This repository was created as a "vibe coding" practice project using Claude Code - Anthropic's AI-powered coding assistant. The entire library was developed through conversational AI pair programming, demonstrating how AI tools can assist in creating production-ready Python packages.

Overview

The USPS Intelligent Mail Barcode (IMb), also known as the OneCode or 4-State Customer Barcode, is used by the United States Postal Service to sort and track letters and flats. This library provides functions to encode tracking and routing data into barcode strings and decode barcode strings back into their component data.

Installation

pip install pyimb

Quick Start

Encoding

from pyimb import encode

# Basic encoding with tracking data only
barcode = encode(
    barcode_id="01",
    service_type="234",
    mailer_id="567094",
    serial_num="987654321"
)
print(barcode)  # 65-character string like "AADTFFDFTDAADTAAFFDTDDAAADTDTTFTDDTADADTDAATFDTDTDTDADDATATADDAATDF"

# Encoding with routing (ZIP code) information
barcode = encode(
    barcode_id="01",
    service_type="234",
    mailer_id="567094",
    serial_num="987654321",
    zip_code="12345",
    plus4="6789",
    delivery_pt="01"
)

Decoding

from pyimb import decode

# Decode a barcode string
result = decode("AADTFFDFTDAADTAAFFDTDDAAADTDTTFTDDTADADTDAATFDTDTDTDADDATATADDAATDF")

print(result.barcode_id)    # "01"
print(result.service_type)  # "234"
print(result.mailer_id)     # "567094"
print(result.serial_num)    # "987654321"
print(result.zip_code)      # "12345" or None
print(result.plus4)         # "6789" or None
print(result.delivery_pt)   # "01" or None

# For 9-digit mailer IDs, specify the length
result = decode(barcode, mailer_id_length=9)

Using IMBData directly

from pyimb import IMBData, encode_from_data

# Create IMBData object
data = IMBData(
    barcode_id="01",
    service_type="234",
    mailer_id="567094",
    serial_num="987654321",
    zip_code="12345"
)

# Encode from IMBData
barcode = encode_from_data(data)

API Reference

encode(barcode_id, service_type, mailer_id, serial_num, zip_code=None, plus4=None, delivery_pt=None)

Encodes tracking and routing information into a 65-character barcode string.

Parameters:

• barcode_id (str): 2-digit barcode identifier (second digit must be 0-4)
• service_type (str): 3-digit service type code
• mailer_id (str): 6 or 9-digit mailer ID
• serial_num (str): Serial number (9 digits for 6-digit mailer ID, 6 digits for 9-digit mailer ID)
• zip_code (str, optional): 5-digit ZIP code
• plus4 (str, optional): 4-digit ZIP+4 extension (requires zip_code)
• delivery_pt (str, optional): 2-digit delivery point (requires plus4)

Returns: A 65-character string containing only 'F', 'A', 'D', 'T' characters.

decode(barcode, mailer_id_length=6)

Decodes a 65-character barcode string into its component data.

Parameters:

• barcode (str): 65-character barcode string
• mailer_id_length (int): Length of mailer ID (6 or 9, default: 6)

Returns: An IMBData object containing the decoded fields.

IMBData

A dataclass representing Intelligent Mail Barcode data.

Attributes:

• barcode_id: 2-digit barcode identifier
• service_type: 3-digit service type code
• mailer_id: 6 or 9-digit mailer ID
• serial_num: Serial number
• zip_code: 5-digit ZIP code (or None)
• plus4: 4-digit ZIP+4 extension (or None)
• delivery_pt: 2-digit delivery point (or None)

Barcode Format

The IMb uses 65 bars, each with 4 possible states:

• F (Full): Both ascender and descender
• A (Ascender): Ascender only
• D (Descender): Descender only
• T (Tracker): Neither (baseline only)

The barcode encodes:

• Tracking Code: barcode_id + service_type + mailer_id + serial_num (20 digits total)
• Routing Code: Optional ZIP, ZIP+4, or ZIP+4+delivery point

Validation

The library validates all input data:

• Barcode ID must be 2 digits with second digit 0-4
• Service type must be 3 digits
• Mailer ID must be 6 or 9 digits
• Serial number length must match mailer ID length (9 digits for 6-digit mailer, 6 digits for 9-digit mailer)
• ZIP code must be 5 digits
• Plus4 must be 4 digits (and requires ZIP code)
• Delivery point must be 2 digits (and requires Plus4)

Exceptions

• IMBError: Base exception for all IMB-related errors
• IMBEncodingError: Raised when encoding fails
• IMBDecodingError: Raised when decoding fails
• IMBValidationError: Raised when input validation fails

from pyimb import encode
from pyimb.exceptions import IMBValidationError

try:
    barcode = encode("99", "234", "567094", "987654321")  # Invalid: second digit > 4
except IMBValidationError as e:
    print(f"Validation error: {e}")

License

This project is released under the CC0 1.0 Universal license.

Credits & Acknowledgments

This library was built with inspiration and reference from the following projects:

• BossRoxall/imb - The original Node.js Intelligent Mail Barcode library that inspired this Python port
• samrushing/pyimb - A reference Python implementation that helped verify the correct BAR_TABLE encoding
• USPS-B-3200 - The official USPS Intelligent Mail Barcode specification document

Special thanks to these open source projects for making their code available!

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.