Preferences
Preferences apply to every message your organization sends. In the portal they are under Settings → Sending.
The preferences object
Section titled “The preferences object”| Field | Type | Default | Description |
|---|---|---|---|
cooldownMs |
integer | 3000 | Pause between two messages on the same phone. Protects your SIMs from carrier spam filters. |
jitterMs |
integer | 2000 | Random extra pause, 0 to this value, added to the cooldown. |
maxRetries |
integer | 2 | Retries after a phone reports a send failure. |
defaultDeviceId |
string or null | The default phone. | |
defaultSimId |
string or null | The default SIM. Set automatically to the first SIM of your first paired phone. | |
sendWindow |
object or null | null |
{ start, end, tz }: live messages outside this daily window wait until it opens. |
forwardInbound |
object or null | null |
{ email?, phone?, webhook? }: where to copy inbound SMS. See Forward inbound messages. |
timeZone |
string | UTC |
The organization’s IANA zone. Campaigns use it for numbers without a country. |
Retrieve preferences
Section titled “Retrieve preferences”GET
/v1/preferencesAny API key or user of the organization can read them; no scope is needed.
curl https://api.smsfabric.com/v1/preferences \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "cooldownMs": 3000, "jitterMs": 2000, "maxRetries": 2, "defaultDeviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "defaultSimId": "sim_r2t4v6x8z1b3d5f7h9j2l4n6", "sendWindow": { "start": "08:00", "end": "22:00", "tz": "Africa/Cairo" }, "forwardInbound": { "email": "support@acme.example" }, "timeZone": "Africa/Cairo"}Update preferences
Section titled “Update preferences”PATCH
/v1/preferencessettings:manageSend only the fields to change. null clears sendWindow, forwardInbound, defaultDeviceId or defaultSimId. Returns the preferences. Audited as preferences.updated.
| Body field | Type | Constraints |
|---|---|---|
cooldownMs |
integer | 0 to 600,000. |
jitterMs |
integer | 0 to 600,000. |
maxRetries |
integer | 0 to 10. |
defaultDeviceId |
string or null | A phone in your organization. |
defaultSimId |
string or null | A SIM in your organization. |
sendWindow |
object or null | start and end as HH:mm (24-hour), tz an IANA zone. |
forwardInbound |
object or null | email (valid email), phone (E.164), webhook (public https URL, checked like webhook endpoints). |
timeZone |
string | An IANA zone. |
curl -X PATCH https://api.smsfabric.com/v1/preferences \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"sendWindow": {"start": "08:00", "end": "22:00", "tz": "Africa/Cairo"}, "cooldownMs": 5000}'| Error | When |
|---|---|
400 validation_failed |
Unknown phone or SIM, an unknown time zone, or a bad HH:mm. |
400 ssrf_blocked |
forwardInbound.webhook is not a public https URL. |