Delivery Reports & Logs

Track message delivery status, analyze performance metrics, and troubleshoot delivery issues with comprehensive reporting and logging.

Delivery Status Types

Status Codes

• Sent: Message submitted to carrier
• Delivered: Successfully delivered to recipient
• Failed: Delivery failed (invalid number, blocked, etc.)
• Pending: Awaiting delivery confirmation
• Expired: Message expired before delivery

Detailed Status Codes

# Get detailed status information
lineserve messaging get-delivery-status \
  --message-id msg-12345 \
  --include-details

Code	Status	Description
1000	Delivered	Successfully delivered
2000	Failed	Invalid phone number
2001	Failed	Blocked by carrier
2002	Failed	Insufficient credit
3000	Pending	Queued for delivery

Real-time Delivery Tracking

Webhooks

# Configure delivery webhooks
lineserve messaging set-webhook \
  --url "https://yourapp.com/webhook/delivery" \
  --events "delivered,failed,pending" \
  --secret "your-webhook-secret"

Webhook Payload

{
  "event": "message.delivered",
  "timestamp": "2024-01-15T10:30:00Z",
  "message_id": "msg-12345",
  "campaign_id": "camp-67890",
  "phone": "+1234567890",
  "status": "delivered",
  "carrier": "Verizon",
  "cost": 0.0075,
  "delivery_time": "2024-01-15T10:30:15Z"
}

Processing Webhooks

# Python webhook handler
from flask import Flask, request
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhook/delivery', methods=['POST'])
def delivery_webhook():
    # Verify webhook signature
    signature = request.headers.get('X-Lineserve-Signature')
    payload = request.get_data()
    
    expected = hmac.new(
        b'your-webhook-secret',
        payload,
        hashlib.sha256
    ).hexdigest()
    
    if signature == expected:
        data = request.json
        
        if data['event'] == 'message.delivered':
            # Update delivery status in your database
            update_message_status(data['message_id'], 'delivered')
        elif data['event'] == 'message.failed':
            # Handle failed delivery
            handle_failed_delivery(data)
    
    return 'OK'

Delivery Reports

Campaign Reports

# Generate campaign delivery report
lineserve messaging get-campaign-report \
  --campaign-id camp-12345 \
  --format json \
  --include-details

# Export to CSV
lineserve messaging export-campaign-report \
  --campaign-id camp-12345 \
  --format csv \
  --output campaign-report.csv

Bulk Message Reports

# Get delivery report for multiple messages
lineserve messaging get-bulk-report \
  --message-ids "msg-1,msg-2,msg-3" \
  --format json

# Get report by date range
lineserve messaging get-delivery-report \
  --start-date "2024-01-01" \
  --end-date "2024-01-31" \
  --status "all"

Report Data Structure

{
  "campaign_id": "camp-12345",
  "campaign_name": "Summer Sale",
  "total_messages": 10000,
  "delivered": 9850,
  "failed": 150,
  "pending": 0,
  "delivery_rate": 98.5,
  "average_delivery_time": "00:00:45",
  "cost_total": 75.00,
  "messages": [
    {
      "message_id": "msg-12345",
      "phone": "+1234567890",
      "status": "delivered",
      "sent_at": "2024-01-15T10:00:00Z",
      "delivered_at": "2024-01-15T10:00:30Z",
      "carrier": "Verizon",
      "cost": 0.0075
    }
  ]
}

Message Logs

Accessing Logs

# View recent message logs
lineserve messaging get-logs \
  --limit 100 \
  --status "failed"

# Search logs by phone number
lineserve messaging search-logs \
  --phone "+1234567890" \
  --start-date "2024-01-01"

# Filter logs by campaign
lineserve messaging get-logs \
  --campaign-id camp-12345 \
  --include-content

Log Entry Format

{
  "log_id": "log-67890",
  "timestamp": "2024-01-15T10:00:00Z",
  "message_id": "msg-12345",
  "campaign_id": "camp-67890",
  "phone": "+1234567890",
  "sender_id": "YourBrand",
  "message": "Your order has shipped!",
  "status": "delivered",
  "carrier": "Verizon",
  "country": "US",
  "cost": 0.0075,
  "delivery_time": 30,
  "error_code": null,
  "error_message": null
}

Analytics Dashboard

Key Metrics

# Get delivery analytics
lineserve messaging get-analytics \
  --metric "delivery_rate" \
  --period "last_30_days" \
  --group-by "day"

# Carrier performance analysis
lineserve messaging analyze-carriers \
  --start-date "2024-01-01" \
  --end-date "2024-01-31"

Performance Metrics

• Delivery Rate: Percentage of successfully delivered messages
• Average Delivery Time: Time from send to delivery
• Failure Rate: Percentage of failed deliveries
• Cost per Message: Average cost per delivered message
• Carrier Performance: Delivery rates by carrier

Custom Analytics

# Python analytics example
import requests
import pandas as pd

def get_delivery_analytics(start_date, end_date):
    response = requests.get(
        'https://api.lineserve.com/v1/messaging/analytics/delivery',
        headers={'Authorization': 'Bearer YOUR_TOKEN'},
        params={
            'start_date': start_date,
            'end_date': end_date,
            'group_by': 'hour'
        }
    )
    
    data = response.json()
    df = pd.DataFrame(data['metrics'])
    
    # Calculate delivery rate trends
    df['delivery_rate'] = (df['delivered'] / df['total']) * 100
    
    return df

# Generate analytics report
analytics = get_delivery_analytics('2024-01-01', '2024-01-31')
print(analytics.describe())

Troubleshooting Failed Deliveries

Common Failure Reasons

# Analyze failure reasons
lineserve messaging analyze-failures \
  --start-date "2024-01-01" \
  --end-date "2024-01-31" \
  --group-by "error_code"

Failure Categories

• Invalid Numbers: Incorrect or non-existent phone numbers
• Carrier Blocks: Messages blocked by carrier filters
• Content Issues: Spam-like content or prohibited keywords
• Rate Limits: Exceeded sending rate limits
• Account Issues: Insufficient balance or suspended account

Retry Logic

# Configure automatic retries
lineserve messaging set-retry-policy \
  --max-retries 3 \
  --retry-interval "5m,15m,1h" \
  --retry-codes "3000,3001"

# Manual retry for failed messages
lineserve messaging retry-failed \
  --campaign-id camp-12345 \
  --error-codes "2001,3000"

Monitoring & Alerts

Delivery Monitoring

# Set up delivery rate alerts
lineserve messaging create-alert \
  --name "Low Delivery Rate" \
  --condition "delivery_rate < 95" \
  --period "15m" \
  --notification "email:admin@company.com"

# Monitor specific campaigns
lineserve messaging monitor-campaign \
  --campaign-id camp-12345 \
  --alert-threshold 90 \
  --notification "slack:ops-channel"

Real-time Monitoring

# Python monitoring script
import requests
import time

def monitor_delivery_rates():
    while True:
        response = requests.get(
            'https://api.lineserve.com/v1/messaging/analytics/realtime',
            headers={'Authorization': 'Bearer YOUR_TOKEN'}
        )
        
        data = response.json()
        delivery_rate = data['delivery_rate']
        
        if delivery_rate < 95:
            send_alert(f"Delivery rate dropped to {delivery_rate}%")
        
        time.sleep(300)  # Check every 5 minutes

def send_alert(message):
    # Send alert via email, Slack, etc.
    pass

Data Export & Integration

Export Options

# Export delivery data to CSV
lineserve messaging export-delivery-data \
  --start-date "2024-01-01" \
  --end-date "2024-01-31" \
  --format csv \
  --output delivery-report.csv

# Export to JSON for API integration
lineserve messaging export-delivery-data \
  --campaign-id camp-12345 \
  --format json \
  --compress

Database Integration

-- SQL schema for delivery tracking
CREATE TABLE message_deliveries (
    message_id VARCHAR(50) PRIMARY KEY,
    campaign_id VARCHAR(50),
    phone VARCHAR(20),
    status VARCHAR(20),
    sent_at TIMESTAMP,
    delivered_at TIMESTAMP,
    carrier VARCHAR(50),
    cost DECIMAL(10,4),
    error_code VARCHAR(10),
    error_message TEXT
);

-- Index for performance
CREATE INDEX idx_campaign_status ON message_deliveries(campaign_id, status);
CREATE INDEX idx_phone_date ON message_deliveries(phone, sent_at);

API Integration

# Sync delivery data to your database
import requests
import sqlite3

def sync_delivery_data():
    # Get recent delivery updates
    response = requests.get(
        'https://api.lineserve.com/v1/messaging/delivery-updates',
        headers={'Authorization': 'Bearer YOUR_TOKEN'},
        params={'since': get_last_sync_time()}
    )
    
    updates = response.json()
    
    # Update local database
    conn = sqlite3.connect('deliveries.db')
    for update in updates['data']:
        conn.execute('''
            INSERT OR REPLACE INTO message_deliveries 
            (message_id, status, delivered_at, carrier, cost)
            VALUES (?, ?, ?, ?, ?)
        ''', (
            update['message_id'],
            update['status'],
            update['delivered_at'],
            update['carrier'],
            update['cost']
        ))
    
    conn.commit()
    conn.close()

Compliance & Reporting

Regulatory Reporting

# Generate compliance report
lineserve messaging generate-compliance-report \
  --type "tcpa" \
  --start-date "2024-01-01" \
  --end-date "2024-12-31" \
  --include-opt-outs

# Export audit trail
lineserve messaging export-audit-trail \
  --start-date "2024-01-01" \
  --format json \
  --include-metadata

Data Retention

# Configure log retention
lineserve messaging set-retention-policy \
  --delivery-logs 90 \
  --message-content 30 \
  --analytics-data 365

API Reference

Get Delivery Status

GET /v1/messaging/messages/{message_id}/delivery

Delivery Reports

GET /v1/messaging/campaigns/{campaign_id}/delivery-report

Message Logs

GET /v1/messaging/logs?start_date=2024-01-01&end_date=2024-01-31

Webhook Configuration

POST /v1/messaging/webhooks
{
  "url": "https://yourapp.com/webhook",
  "events": ["delivered", "failed"],
  "secret": "webhook-secret"
}

Best Practices

Monitoring Setup

• Set up real-time delivery monitoring
• Configure alerts for delivery rate drops
• Monitor carrier-specific performance
• Track cost trends and optimization opportunities

Data Management

• Implement proper data retention policies
• Regular backup of delivery logs
• Efficient database indexing for queries
• Automated reporting and analytics

Troubleshooting

• Monitor failure patterns and trends
• Implement retry logic for transient failures
• Regular review of blocked numbers
• Carrier relationship management

Next Steps

• Set up campaign management
• Configure sender IDs
• Implement webhooks
• Optimize delivery rates