I'm building a product that needs SMS delivery receipts and logs

Got it. If you need SMS delivery receipts and logs, there are a few key things to design for up front so the system is reliable and auditable.

What you typically need

1. Message lifecycle tracking

Track each SMS through states like:

• queued
• sent
• delivered
• failed
• undeliverable
• expired
• unknown

2. Delivery receipts

Use your SMS provider’s delivery report / webhook / callback support so you can update message status when the carrier reports back.

3. Centralized logs

Store:

• message ID
• recipient number
• sender ID / long code / short code
• timestamps for each status change
• provider response payloads
• error codes and failure reasons
• retries attempted
• correlated user/account identifiers

4. Event ingestion pipeline

Delivery receipts usually arrive asynchronously, so your system should:

• receive webhooks
• validate authenticity
• deduplicate events
• map provider message IDs to your internal IDs
• persist raw payloads for auditing
• update the canonical message record

5. Searchable audit trail

You’ll want logs that support queries like:

• “Show all messages for customer X last 7 days”
• “Why did message Y fail?”
• “What percentage were delivered by carrier A?”
• “Show all events for one message in time order”

Recommended data model

At minimum:

messages

• id
• user_id
• to_number
• from_number
• body
• provider
• provider_message_id
• status
• created_at
• sent_at
• delivered_at
• failed_at

message_events

• id
• message_id
• event_type
• provider_status
• error_code
• error_message
• payload_json
• created_at

This lets you keep:

• the latest state on messages
• a full timeline in message_events

Important implementation details

Webhook validation

Make sure delivery receipt callbacks are authenticated:

• HMAC signature checks
• allowlisted IPs if supported
• replay protection if available

Idempotency

Carriers/providers may send the same receipt multiple times. Deduplicate by:

• provider message ID
• event type
• receipt timestamp
• raw payload hash

Status normalization

Different providers use different terminology. Normalize into your own internal enum.

Example:

• provider says DELIVRD → internal delivered
• provider says UNDELIV → internal failed
• provider says EXPIRED → internal expired

Retention and compliance

SMS logs can include sensitive data, so consider:

• retention policies
• encryption at rest
• access controls
• PII masking
• regional compliance requirements

Provider choice

If you haven’t picked one yet, choose an SMS provider that supports:

• delivery receipts/webhooks
• message status APIs
• detailed error codes
• message search/export
• sandbox/testing tools

Common options include:

• Twilio
• Vonage
• Sinch
• MessageBird
• Plivo
• Telnyx

Questions to narrow this down

If you want, I can help design this for your exact use case. Helpful details:

1. Which SMS provider are you using?
2. Do you need carrier-level delivery receipts, or just provider-level status?
3. Do you need logs for compliance/audit, or mainly for product analytics?
4. What stack are you using backend-wise?

If you answer those, I can propose a concrete architecture and schema.