hr-birthday-letters 0.1.2

Generate milestone birthday letters for employees and deliver them through managers.

HR Birthday Letter Generator

A simple Python project to generate milestone birthday letters for employees and deliver them through managers. It can be used from the command line or through a small desktop app for office users.

Project structure

• generate_birthday_letters.py - package entrypoint script
• birthday_letters_app.py - desktop app entrypoint
• Start Birthday Letters.bat - Windows launcher for the desktop app
• hr_birthday_letters/ - package source code
• hr_birthday_letters/templates/ - language-specific mail cover and PDF letter templates
• employees.csv - sample employee data file
• tests/ - unit tests
• output/ - generated mail cover text files and PDF letters are saved here by default

CSV Format

Required columns:

• Name
• DateOfBirth (YYYY-MM-DD)
• Manager
• Language (matches a template file such as en.txt or nl.txt)

Optional columns:

• ManagerEmail (required when creating Outlook mails)
• EmployeeEmail
• Department
• Location

Example:

Name,DateOfBirth,Manager,ManagerEmail,Language,Department,Location
Alice Johnson,1996-05-28,Michael Smith,[e-mail],en,Engineering,New York
Ella Rodriguez,2001-05-28,Michael Smith,[e-mail],nl,Engineering,New York

Templates

Templates are plain text files stored in hr_birthday_letters/templates/ by default. The employee Language value selects matching templates for both outputs:

• The mail cover text uses hr_birthday_letters/templates/cover/<language>.txt
• The PDF birthday letter uses hr_birthday_letters/templates/letter/<language>.txt

For example, en uses both:

• hr_birthday_letters/templates/cover/en.txt
• hr_birthday_letters/templates/letter/en.txt

The cover text is high level and addressed to the manager. The PDF letter is addressed to the employee whose birthday milestone is being recognized.

Available placeholders:

• $date
• $manager
• $manager_email
• $employee_name
• $employee_email
• $birthday
• $age
• $department
• $location
• $language

Install

Use Python 3.9+ and install the package in editable mode:

cd C:\Users\KRIJDI01\hr-birthday-letters
python -m pip install -e .

For Outlook desktop integration on Windows, install the optional office dependency:

python -m pip install -e ".[office]"

Desktop app

Start the app:

.\Start Birthday Letters.bat

Or run it with Python:

python birthday_letters_app.py

Or use the installed script:

hr-birthday-letters-ui

The app lets an office user:

• Select the employee CSV, output folder, and template folder
• Generate mail cover text files and PDF birthday letters
• Maintain cover and PDF letter templates by language
• Create Outlook drafts with the PDF attached
• Open Outlook mails for review or send immediately after confirmation

Run

python generate_birthday_letters.py employees.csv

Or use the installed CLI script:

hr-birthday-letters employees.csv

To specify a different output directory:

hr-birthday-letters employees.csv --output-dir letters

To use a custom template directory:

hr-birthday-letters employees.csv --template-dir templates

To create Outlook drafts from the command line:

hr-birthday-letters employees.csv --create-outlook-drafts

Other Outlook options:

hr-birthday-letters employees.csv --open-outlook-mails
hr-birthday-letters employees.csv --send-outlook-mails

The custom directory should use the same layout:

templates/
  cover/
    en.txt
    nl.txt
  letter/
    en.txt
    nl.txt

Test

Install the test dependencies first:

python -m pip install -e .[test]
python -m pytest

How it works

• Reads employee rows from a CSV file
• Computes each employee's age as of today
• Generates the cover text and PDF letter only when the age is a positive multiple of 5
• Selects cover and letter templates using the employee's Language value
• Saves one manager-facing mail cover text file per eligible employee
• Saves one employee-facing birthday letter PDF per eligible employee
• Uses ManagerEmail to create Outlook mails with the PDF attached