Skip to content

Commit fe05df4

Browse files
AchoArnoldCopilot
AchoArnold
and
Copilot
committed
docs: add outgoing message queue technical documentation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 704355d commit fe05df4

1 file changed

Lines changed: 173 additions & 0 deletions

File tree

‎outgoing-message-queue.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Outgoing Message Queue
2+
3+
Complete guide on how httpSMS queues outgoing SMS messages for reliable delivery, including rate-based dispatch, scheduled sending, and send schedule windows.
4+
5+
## How the Message Queue Works
6+
7+
When you send an SMS through httpSMS (via the API, bulk send, or Excel upload), messages don't go directly to your Android phone. Instead, they enter an **outgoing message queue** that intelligently schedules delivery to ensure reliability and prevent carrier throttling.
8+
9+
The queue determines **when** each message is dispatched to your phone based on three factors:
10+
11+
1. **Explicit send time** — If you specify a `send_at` time, the message is sent at exactly that time
12+
2. **Rate-based dispatch delay** — Messages without a send time are spaced out based on your configured send rate
13+
3. **Send schedule window** — Messages can be held until your configured active hours (if enabled)
14+
15+
## 1. Explicit Send Time (Bypass Queue Logic)
16+
17+
When you specify a `send_at` time in your API request or a `SendTime` column in your Excel upload, the message **bypasses** both rate-limiting and schedule window logic entirely. The message will be dispatched to your phone at exactly the time you specified.
18+
19+
This is ideal for:
20+
21+
- Time-sensitive alerts that must go out at a precise moment
22+
- Promotional messages timed for a specific campaign window
23+
- Appointment reminders scheduled for a specific time before the appointment
24+
25+
### Sending a single message at a specific time
26+
27+
```bash
28+
curl -L \
29+
--request POST \
30+
--url 'https://api.httpsms.com/v1/messages/send' \
31+
--header 'Content-Type: application/json' \
32+
--header 'x-api-Key: YOUR_API_KEY' \
33+
--data '{
34+
"from": "+18005550199",
35+
"to": "+18005550100",
36+
"content": "Your appointment is in 1 hour",
37+
"send_at": "2025-12-19T16:39:57-08:00"
38+
}'
39+
```
40+
41+
The `send_at` field accepts time in [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339) which includes the time zone (e.g., `1996-12-19T16:39:57-08:00`). You can schedule messages up to 20 days (480 hours) in the future.
42+
43+
> **Note:** If you specify a `send_at` time that is in the past, the message will be sent immediately.
44+
45+
### Setting send time in bulk Excel uploads
46+
47+
When using the [bulk messages Excel template](https://httpsms.com/templates/httpsms-bulk.xlsx), you can set the optional `SendTime(optional)` column to specify when each message should be sent. Use the format `YYYY-MM-DDTHH:MM:SS` in your local time zone (e.g., `2023-11-13T02:10:01`).
48+
49+
Each row with a `SendTime` value will be dispatched at exactly that time, independent of other messages in the batch.
50+
51+
## 2. Rate-Based Dispatch Delay
52+
53+
When you send messages **without** a `send_at` time (especially in bulk), httpSMS automatically spaces out delivery based on your phone's configured **Messages Per Minute** rate. This prevents carrier throttling and ensures reliable delivery.
54+
55+
### How rate-based dispatch works
56+
57+
The system calculates a dispatch delay for each message based on its position in the batch:
58+
59+
```
60+
interval = 60 seconds ÷ messages_per_minute
61+
delay = message_index × interval
62+
```
63+
64+
**Example:** If your phone is configured for 10 messages per minute:
65+
66+
| Message | Index | Delay | Dispatched At |
67+
| ------- | ----- | ----- | ------------- |
68+
| 1st | 0 | 0s | Immediately |
69+
| 2nd | 1 | 6s | +6 seconds |
70+
| 3rd | 2 | 12s | +12 seconds |
71+
| 4th | 3 | 18s | +18 seconds |
72+
| 10th | 9 | 54s | +54 seconds |
73+
74+
This ensures your phone sends at most 10 SMS per minute, matching the configured rate.
75+
76+
### Per-phone indexing for bulk sends
77+
78+
When sending bulk messages to multiple recipients from the same phone number, the index is calculated per phone. This means messages to different recipient numbers are all spaced according to the sending phone's rate, ensuring the sending phone isn't overwhelmed.
79+
80+
When using Excel/CSV uploads with multiple sender phones (different `From` numbers), each phone gets its own independent index counter. Messages from Phone A don't affect the timing of messages from Phone B.
81+
82+
### Configuring Messages Per Minute
83+
84+
To modify the send rate for your phone number:
85+
86+
1. Go to [https://httpsms.com/settings](https://httpsms.com/settings#phones)
87+
2. Tap the **"EDIT"** button on the phone number
88+
3. Update the **"Messages Per Minute"** value
89+
90+
**Default:** 10 messages per minute for newly registered phones.
91+
92+
**Maximum:** 29 messages per minute (the [maximum permitted by an unrooted Android phone](https://android.googlesource.com/platform/frameworks/opt/telephony/+/master/src/java/com/android/internal/telephony/SmsUsageMonitor.java#84)).
93+
94+
> **Tip:** If you're sending large batches, a lower rate (5-10/min) is more reliable. Higher rates (20+/min) may trigger carrier spam filters depending on your region.
95+
96+
## 3. Send Schedule Window
97+
98+
The send schedule window allows you to restrict message delivery to specific hours of the day. When enabled, messages sent outside the configured window are held in the queue and dispatched when the next window opens.
99+
100+
This is useful for:
101+
102+
- Respecting recipient quiet hours (no messages at 3 AM)
103+
- Complying with regional messaging regulations
104+
- Concentrating delivery during business hours
105+
106+
> **Important:** Messages with an explicit `send_at` time bypass the send schedule window entirely. Only messages without a specified send time are subject to window restrictions.
107+
108+
### Configuring the Send Schedule
109+
110+
You can configure the send schedule window for each phone number in your account settings at [https://httpsms.com/settings](https://httpsms.com/settings#phones). Click **"EDIT"** on the phone number and set:
111+
112+
- **Schedule Active** — Enable or disable the schedule window
113+
- **Start Time** — The time of day when sending begins (e.g., `08:00`)
114+
- **End Time** — The time of day when sending stops (e.g., `21:00`)
115+
- **Timezone** — The timezone for the schedule (e.g., `America/New_York`)
116+
117+
### How the schedule window works
118+
119+
| Current Time vs Window | Behavior |
120+
| ---------------------- | ------------------------------------------------------ |
121+
| Within window | Message dispatched immediately (subject to rate delay) |
122+
| Before window opens | Message held until window start time |
123+
| After window closes | Message held until next day's window start time |
124+
125+
## Bulk Send via API
126+
127+
When sending to multiple recipients using the bulk API endpoint, all messages are automatically queued with rate-based dispatch delays:
128+
129+
```bash
130+
curl -L \
131+
--request POST \
132+
--url 'https://api.httpsms.com/v1/messages/bulk-send' \
133+
--header 'Content-Type: application/json' \
134+
--header 'x-api-Key: YOUR_API_KEY' \
135+
--data '{
136+
"from": "+18005550199",
137+
"to": ["+18005550100", "+18005550101", "+18005550102"],
138+
"content": "Hello from httpSMS!"
139+
}'
140+
```
141+
142+
In this example, with a default rate of 10 messages/minute:
143+
144+
- Message to `+18005550100` → sent immediately
145+
- Message to `+18005550101` → sent after 6 seconds
146+
- Message to `+18005550102` → sent after 12 seconds
147+
148+
## Summary: Queue Decision Flow
149+
150+
```
151+
Message received by httpSMS API
152+
│
153+
├── Has explicit `send_at` time?
154+
│ │
155+
│ YES → Dispatch at exactly that time
156+
│ (bypasses rate-limit AND schedule window)
157+
│
158+
└── No `send_at` time
159+
│
160+
├── Calculate rate-based delay
161+
│ (index × 60s ÷ messages_per_minute)
162+
│
163+
└── Apply send schedule window
164+
(hold until window opens if outside active hours)
165+
```
166+
167+
## Key Points
168+
169+
- **Explicit send time always wins** — Setting `send_at` bypasses all queue logic
170+
- **Rate limiting prevents throttling** — Messages are spaced based on your configured rate
171+
- **Schedule windows respect quiet hours** — Messages without a send time are held until the window opens
172+
- **Per-phone independence** — Each sending phone has its own rate counter and schedule
173+
- **Past send times are handled gracefully** — If `send_at` is in the past, the message sends immediately

0 commit comments

Comments
 (0)