MessageBird SMS
SMS messaging via the MessageBird (Bird) API. Used for two-factor authentication, appointment reminders, and portal notifications.
Architecture
| Component | Path |
|---|---|
| SMS client | backend/src/lib/sms/ |
| Notification service | backend/src/services/notification-service.ts |
Configuration
| Secret | Purpose |
|---|---|
BIRD_API_KEY | MessageBird API authentication |
SMS_CATCH_ALL_PHONE_NUMBERS | Test safety redirect (non-production) |
Secrets stored as GitHub Environment Secrets, synced to Fly.io. See Deployment Pipeline.
SMS Types
| Category | Trigger | Related Feature |
|---|---|---|
| 2FA verification code | User enables phone 2FA | Authentication |
| Appointment reminder | Upcoming appointment | Appointments |
| Portal notification | Document request or update | Portal, Document Obtaining |
| Status update | Project milestone reached | Projects |
Test Safety
In non-production environments, the SMS_CATCH_ALL_PHONE_NUMBERS environment variable redirects all SMS to designated test phone numbers. This prevents accidentally sending SMS to real customers during development and staging.
| Environment | Behavior |
|---|---|
| Development | All SMS redirected to catch-all numbers |
| Staging | All SMS redirected to catch-all numbers |
| Production | SMS sent to actual recipient numbers |
Background Processing
SMS messages are sent asynchronously via the notification queue:
- Service enqueues SMS job with recipient + message
- Background Jobs processor sends via MessageBird API
- Delivery status is tracked and logged
This pattern is shared with Resend Email — both use the same notification queue infrastructure.
Phone Number Handling
Phone numbers are stored in E.164 format (+49123456789). The SMS client validates format before sending. Invalid numbers are rejected with a descriptive error logged to Sentry.
Related
- Notifications — Notification dispatch architecture
- Authentication — 2FA verification codes
- Appointments — Appointment reminder SMS
- Portal — Portal notification SMS
- Background Jobs — Async SMS processing queue
- External Integrations — All third-party integrations
- Sentry — Delivery failure tracking