Skip to content

Send and receive SMS messages using your Android phone programmatically via a simple HTTP API

docs: link to existing feature pages instead of re-explaining scheduling and send rate

Acho Arnold93d8ac9f6dac
diff --git a/docs/superpowers/plans/2026-05-03-scheduling-send-refactor.md b/docs/superpowers/plans/2026-05-03-scheduling-send-refactor.md
index a85b46ed..f92b60ed 100644
--- a/docs/superpowers/plans/2026-05-03-scheduling-send-refactor.md
+++ b/docs/superpowers/plans/2026-05-03-scheduling-send-refactor.md
@@ -4,7 +4,12 @@
**Goal:** Allow users to send SMS at an exact time (bypassing scheduling) when `SendAt` is specified, and replace the 1-second bulk hack with rate-based dispatch delays.
-**Architecture:** Add a transient `ExactSendTime` flag flowing through the event system. When true, bypass rate-limit and schedule window logic in notification scheduling. For bulk sends without explicit time, compute dispatch delay from `MessagesPerMinute` per-phone instead of hardcoded 1s.
+**Related docs:**
+
+- [Scheduling SMS Messages](https://docs.httpsms.com/features/scheduling-sms-messages) — the existing `SendAt`/`SendTime` feature
+- [Control SMS Send Rate](https://docs.httpsms.com/features/control-sms-send-rate) — the existing `MessagesPerMinute` rate-limiting feature
+
+**Architecture:** Add a transient `ExactSendTime` flag flowing through the event system. When true, bypass [rate-limit](https://docs.httpsms.com/features/control-sms-send-rate) and schedule window logic in notification scheduling. For bulk sends without explicit time, compute dispatch delay from `MessagesPerMinute` per-phone instead of hardcoded 1s.
**Tech Stack:** Go, Fiber, GORM, CockroachDB, Google Cloud Tasks (CloudEvents)
diff --git a/docs/superpowers/specs/2026-05-03-entitlement-service-design.md b/docs/superpowers/specs/2026-05-03-entitlement-service-design.md
index c22b8a9b..8ec3893c 100644
--- a/docs/superpowers/specs/2026-05-03-entitlement-service-design.md
+++ b/docs/superpowers/specs/2026-05-03-entitlement-service-design.md
@@ -2,7 +2,7 @@
## Problem
-The send schedule feature (and future features) need usage limits based on the user's subscription plan. Free users should be limited to 1 send schedule; paid users get unlimited. The system must be:
+The [MessageSendSchedule](./2026-05-03-scheduling-send-refactor-design.md#messagesendschedule-send-windows--new-feature) feature (and future features) need usage limits based on the user's subscription plan. Free users should be limited to 1 send schedule; paid users get unlimited. The system must be:
- **Scalable**: Easy to add new entity limits without architectural changes
- **Configurable**: Disabled by default for self-hosted deployments, enabled via env var for cloud
diff --git a/docs/superpowers/specs/2026-05-03-scheduling-send-refactor-design.md b/docs/superpowers/specs/2026-05-03-scheduling-send-refactor-design.md
index 34d78445..1a02bc08 100644
--- a/docs/superpowers/specs/2026-05-03-scheduling-send-refactor-design.md
+++ b/docs/superpowers/specs/2026-05-03-scheduling-send-refactor-design.md
@@ -1,10 +1,15 @@
# Scheduling Send Refactor Design
+## Related Documentation
+
+- [Scheduling SMS Messages](https://docs.httpsms.com/features/scheduling-sms-messages) — existing `SendAt`/`SendTime` scheduling feature
+- [Control SMS Send Rate](https://docs.httpsms.com/features/control-sms-send-rate) — existing `MessagesPerMinute` rate-limiting feature
+
## Problem Statement
The current SMS scheduling logic has two issues:
-1. **No way to send at an exact time without scheduling interference.** When a user specifies a `SendTime`/`SendAt`, the system still applies rate-limiting and schedule window logic, which may shift the actual send time.
+1. **No way to send at an exact time without scheduling interference.** When a user specifies a `SendTime`/`SendAt` (see [Scheduling SMS Messages](https://docs.httpsms.com/features/scheduling-sms-messages)), the system still applies rate-limiting and schedule window logic, which may shift the actual send time.
2. **Bulk message contention.** When bulk messages (API or CSV) are sent, all events arrive at the Cloud Tasks queue near-simultaneously, causing DB serialization conflicts in `PhoneNotificationRepository.Schedule()` (which uses `SELECT ... ORDER BY scheduled_at DESC` in a transaction). The current workaround is a hardcoded 1-second spacing hack.
@@ -12,8 +17,8 @@ The current SMS scheduling logic has two issues:
### Core Principle
-- **Explicit `SendTime`** = send at exactly that time, bypass all scheduling logic.
-- **No `SendTime`** = apply full scheduling logic (rate-limit + schedule windows), with rate-based Cloud Task dispatch delay to prevent DB contention.
+- **Explicit `SendTime`** = send at exactly that time, bypass all scheduling logic. See [Scheduling SMS Messages](https://docs.httpsms.com/features/scheduling-sms-messages) for how `SendAt` works.
+- **No `SendTime`** = apply full scheduling logic ([rate-limit](https://docs.httpsms.com/features/control-sms-send-rate) + schedule windows), with rate-based Cloud Task dispatch delay to prevent DB contention.
### Design
@@ -111,7 +116,73 @@ User sends request
### What Does NOT Change
- The `MessageSendSchedule` entity and its `ResolveScheduledAt()` logic
-- The `SendScheduleService` CRUD operations
+- The `MessageSendScheduleService` CRUD operations
- The phone notification entity schema (no new DB columns)
- The Android app behavior
- The web frontend (models auto-generated from Swagger)
+
+---
+
+## MessageSendSchedule (Send Windows) — New Feature
+
+This is the only scheduling mechanism that does **not** have a dedicated documentation page yet. Unlike [Scheduling SMS Messages](https://docs.httpsms.com/features/scheduling-sms-messages) (one-time `SendAt`) and [Control SMS Send Rate](https://docs.httpsms.com/features/control-sms-send-rate) (`MessagesPerMinute` throttling), MessageSendSchedule defines **recurring availability windows** that control when a phone is allowed to send outgoing SMS messages.
+
+### Concept
+
+A `MessageSendSchedule` is a named set of time windows (per day of week) that define when the phone can send. Messages arriving outside those windows are delayed until the next available window opens.
+
+### Entity
+
+```go
+type MessageSendSchedule struct {
+ ID uuid.UUID
+ UserID UserID
+ Name string // e.g. "Business Hours"
+ Timezone string // IANA timezone e.g. "Europe/Tallinn"
+ IsActive bool
+ Windows []MessageSendScheduleWindow // per-day availability slots
+ CreatedAt time.Time
+ UpdatedAt time.Time
+}
+
+type MessageSendScheduleWindow struct {
+ DayOfWeek int // 0=Sunday, 6=Saturday
+ StartMinute int // minutes from midnight (e.g. 540 = 9:00)
+ EndMinute int // minutes from midnight (e.g. 1020 = 17:00)
+}
+```
+
+### How It Works
+
+1. A user creates a schedule via `POST /v1/send-schedules` with a name, timezone, and one or more windows.
+2. The schedule is linked to a phone via a `ScheduleID` field on the phone entity.
+3. When a message is queued (without an explicit `SendAt`), the `PhoneNotificationRepository.Schedule()` method calls `MessageSendSchedule.ResolveScheduledAt(now)` to find the next allowed send time.
+4. If the current time falls within a window, the message sends immediately. If not, it's delayed to the start of the next available window.
+
+### API Endpoints
+
+| Method | Endpoint | Description |
+| ------ | --------------------------------- | --------------------------- |
+| GET | `/v1/send-schedules` | List all user schedules |
+| POST | `/v1/send-schedules` | Create a new schedule |
+| PUT | `/v1/send-schedules/{scheduleID}` | Update an existing schedule |
+| DELETE | `/v1/send-schedules/{scheduleID}` | Delete a schedule |
+
+### Validation Rules
+
+- `name`: required, 2–100 characters
+- `timezone`: required, valid IANA timezone
+- `windows[].day_of_week`: 0–6
+- `windows[].start_minute`: 0–1439
+- `windows[].end_minute`: 1–1440, must be greater than `start_minute`
+- Max 6 windows per day
+- No overlapping windows on the same day
+
+### Entitlement
+
+Free users are limited to 1 schedule. Paid users get unlimited schedules. Enforced via `EntitlementService.Check()` in the handler before creation.
+
+### Interaction with Other Scheduling Features
+
+- **[Scheduling SMS Messages](https://docs.httpsms.com/features/scheduling-sms-messages)** (`SendAt`): When provided, bypasses send windows entirely (exact send time).
+- **[Control SMS Send Rate](https://docs.httpsms.com/features/control-sms-send-rate)** (`MessagesPerMinute`): Applied independently — rate-limiting still applies within allowed windows. Both constraints compose: the message must be within a window AND respect the rate limit.