Bulk Messaging System

An Electron Desktop app for marketing campaign & broadcast management, using either whatsapp, gmail or a SMTP server

Source

Flask API endpoints

Introduction#

Flask routes used for upload, validate, parse-manual, and health. Request shapes and the JSON you get back.

  • Health check endpoint for system monitoring
  • File upload endpoint for importing contacts from CSV, TXT, and Excel files
  • Manual number parsing endpoint for direct phone number input
  • Single number validation endpoint for individual phone number verification

It includes request/response schemas, HTTP status codes, error handling patterns, authentication requirements, practical usage examples with curl commands, and guidance on rate limiting, file size limits, and security measures.

Project structure#

The API is implemented in a dedicated Python backend module with a Flask application that exposes four endpoints:

  • Health check: GET /health
  • File upload: POST /upload
  • Manual number parsing: POST /parse-manual-numbers
  • Number validation: POST /validate-number

Core components#

  • Flask application with CORS enabled for cross-origin requests
  • File upload handling with allowed extensions and size limit
  • Phone number cleaning and validation logic
  • Contact extraction from CSV, TXT, and Excel files
  • Manual number parsing with flexible input formats
  • Health check endpoint returning system status

Key configurations:

  • Upload folder: uploads/
  • Allowed file types: txt, csv, xlsx, xls
  • Max content length: 16 MB
  • CORS enabled globally

Architecture overview#

The API follows a straightforward request-response model:

  • Clients send HTTP requests to the endpoints
  • The Flask app validates inputs and performs operations
  • Responses are returned as JSON with appropriate status codes

Detailed component analysis#

Health check endpoint#

  • Path: GET /health
  • Purpose: System monitoring and readiness probe
  • Request: No body required
  • Response:
  • Success: 200 OK with JSON object containing status and message
  • Example curl command:
  • curl -s http://localhost:5000/health
  • Notes:
  • No authentication required
  • Typical use: Kubernetes liveness/readiness probes

Response schema:

  • Field: status (string) - “healthy”
  • Field: message (string) - descriptive status text

HTTP status codes:

  • 200 OK

File upload endpoint#

Request schema:

  • Field: file (binary) - file to upload

Response schema (success):

  • Field: success (boolean) - true
  • Field: contacts (array) - array of contact objects
  • Each contact object:
  • number (string) - normalized phone number
  • name (string or null) - contact name or auto-generated placeholder
  • Field: count (integer) - number of contacts extracted
  • Field: message (string) - operation summary

Response schema (error):

  • Field: error (string) - error description

HTTP status codes:

  • 200 OK (on success)
  • 400 Bad Request (no file, empty filename, invalid file type)
  • 500 Internal Server Error (processing failure)

Processing logic:

  • Validates presence and extension of uploaded file
  • Saves file securely to uploads/ directory
  • Detects file type and parses accordingly:
  • CSV: reads with pandas, detects phone/name columns, cleans numbers
  • TXT: splits by separators, attempts to detect phone number patterns
  • Excel: reads with pandas, similar column detection and cleaning
  • Removes uploaded file after processing

Manual number parsing endpoint#

  • Path: POST /parse-manual-numbers
  • Purpose: Parse manually entered phone numbers with optional names
  • Request:
  • Content-Type: application/json
  • Body: JSON object with numbers field
  • Response:
  • Success: 200 OK with JSON object containing success flag, contacts array, count, and message
  • Error: 400 Bad Request if numbers field is missing, or 500 Internal Server Error for processing failures
  • Example curl command:
  • curl -s -H “Content-Type: application/json” -d ‘{“numbers”:“+1234567890\n555-123-4567”}’ http://localhost:5000/parse-manual-numbers
  • curl -s -H “Content-Type: application/json” -d ‘{“numbers”:“John:+1234567890\nJane:555-123-4567”}’ http://localhost:5000/parse-manual-numbers
  • Notes:
  • Supports newline, comma, and semicolon separators
  • Recognizes “Name: Number” or “Number - Name” formats

Request schema:

  • Field: numbers (string) - one or more phone numbers separated by newlines, commas, or semicolons

Response schema (success):

  • Field: success (boolean) - true
  • Field: contacts (array) - array of contact objects
  • Each contact object:
  • number (string) - normalized phone number
  • name (string or null) - contact name or auto-generated placeholder
  • Field: count (integer) - number of contacts parsed
  • Field: message (string) - operation summary

Response schema (error):

  • Field: error (string) - error description

HTTP status codes:

  • 200 OK (on success)
  • 400 Bad Request (missing numbers field)
  • 500 Internal Server Error (processing failure)

Parsing logic:

  • Splits input by newlines, commas, or semicolons
  • Attempts to split by colon or dash to separate name and number
  • Validates and normalizes each number
  • Ignores empty entries

Single number validation endpoint#

  • Path: POST /validate-number
  • Purpose: Validate and normalize a single phone number
  • Request:
  • Content-Type: application/json
  • Body: JSON object with number field
  • Response:
  • Success: 200 OK with JSON object indicating validity and normalized number
  • Error: 400 Bad Request if number field is missing, or 500 Internal Server Error for processing failures
  • Example curl command:
  • curl -s -H “Content-Type: application/json” -d ‘{“number”:“+1234567890”}’ http://localhost:5000/validate-number
  • Notes:
  • Returns cleaned number if valid, otherwise null

Request schema:

  • Field: number (string) - phone number to validate

Response schema (success):

  • Field: valid (boolean) - true if number is valid, false otherwise
  • Field: cleaned_number (string or null) - normalized number or null if invalid
  • Field: original (string) - original input number

Response schema (error):

  • Field: error (string) - error description

HTTP status codes:

  • 200 OK (on success)
  • 400 Bad Request (missing number field)
  • 500 Internal Server Error (processing failure)

Validation logic:

  • Cleans and normalizes the number using regex rules
  • Validates digit count and format constraints
  • Returns normalized number if valid, null otherwise

Dependency analysis#

External dependencies used by the Flask application:

  • flask: Web framework
  • flask-cors: Enable CORS for cross-origin requests
  • pandas: Read CSV and Excel files
  • openpyxl: Read Excel (.xlsx) files
  • xlrd: Read legacy Excel (.xls) files
  • werkzeug: Secure filename handling

Performance considerations#

  • File size limit: 16 MB enforced via MAX_CONTENT_LENGTH
  • CPU-bound parsing: Regex and pandas operations; large files may take time
  • Memory usage: Depends on file size and number of contacts
  • Recommendations:
  • Validate file sizes client-side before upload
  • Consider streaming or chunked processing for very large files
  • Use asynchronous processing for heavy workloads
  • Implement rate limiting at the application level if needed

Troubleshooting guide#

Common issues and resolutions:

  • Health check fails:
  • Ensure the Flask server is running on the expected host/port
  • Check network connectivity and firewall settings
  • Upload endpoint returns 400:
  • Verify the file field is present and not empty
  • Confirm file extension is one of txt, csv, xlsx, xls
  • Check file size does not exceed 16 MB
  • Upload endpoint returns 500:
  • Inspect server logs for exceptions during file processing
  • Validate file encoding and structure
  • Manual number parsing returns 400:
  • Ensure the JSON body contains a numbers field
  • Number validation returns 400:
  • Ensure the JSON body contains a number field
  • CORS errors:
  • Confirm flask-cors is enabled and origin is allowed
  • Rate limiting:
  • Implement application-level throttling if needed
  • Consider external rate limiting proxies

Conclusion#

These endpoints are intentionally thin wrappers around the extractors. Fix parsing bugs in the utilities, not in the route handlers.

Appendices#

Authentication requirements#

  • No authentication is required for any of the endpoints
  • For production environments, consider adding authentication middleware or API keys

Practical usage examples#

Security measures#

  • CORS enabled globally; restrict origins in production
  • Secure filename handling via werkzeug.secure_filename
  • File type validation against allowed extensions
  • Maximum content length set to 16 MB
  • Consider adding input validation and sanitization

Rate limiting considerations#

  • No built-in rate limiting in the current implementation
  • Recommended approaches:
  • Use Flask-Limiter or similar libraries
  • Implement application-level counters
  • Place a reverse proxy with rate limiting in front of the API

File size limits#

  • Maximum upload size: 16 MB
  • Enforced via Flask’s MAX_CONTENT_LENGTH configuration

Supported file formats#

  • CSV: Comma-separated values with automatic column detection for phone and name
  • TXT: One contact per line; supports “Name: Number” and “Number - Name” formats
  • Excel: .xlsx and .xls files with automatic column detection