Skip to content

Preferences

Preferences apply to every message your organization sends. In the portal they are under Settings → Sending.

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.
GET/v1/preferences

Any API key or user of the organization can read them; no scope is needed.

Terminal window
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"
}
PATCH/v1/preferencessettings:manage

Send 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.
Terminal window
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.