Docs
Open dashboard

Create SMS campaign

POST/sms-campaigns

Creates an SMS campaign with its contacts in one call. No channel field is needed — this URL is the SMS channel. The workspace must have SMS campaigns enabled (an organization owner turns this on under Organization → Workspaces), or the request is rejected with 403. Contacts on the workspace's unsubscribe register are dropped before any row is written; the count comes back as sms_opted_out_excluded. If every contact is opted out the request fails with 400. The campaign lands in ready when it can actually send — a composed message_body (or, with sms_message_source: "flow", an attached automation) plus sms_from_number and sms_carrier — and in draft otherwise, so setup can be finished in the app. Nothing is sent until the campaign is started from the app. message_body supports {{first_name}}, {{last_name}}, {{email}}, {{company}}, {{phone_number}} and any key supplied in a contact's custom_variables.

Requires Authorization: Bearer <api_key>. Create a key in the Inspra dashboard under Workspace Settings → API Keys.

Body application/json

  • channelstringoptional
    Selects this body on POST /campaigns. Implied — and ignored if sent — on POST /sms-campaigns.
    sms
  • namestring1–100 charsrequired
  • descriptionstring0–500 charsoptional
  • sms_modestringoptional
    Recorded, not yet acted on — reply handling ships with SMS delivery.
    Default "one_way"
    one_wayconversational
  • sms_message_sourcestringoptional
    custom sends message_body. flow runs the Automations flow named by sms_flow_id.
    Default "custom"
    customflow
  • message_bodystring0–1600 charsoptional
    The message to send. **Required when sms_message_source=custom.** Messages over 1600 characters cannot be delivered reliably.
  • sms_flow_idstringnullableuuidoptional
    Automations flow that drives the campaign. **Required when sms_message_source=flow**, and must belong to this workspace.
  • sms_carrierstringnullableoptional
    Sending carrier. Required (with sms_from_number) for the campaign to be startable.
    twilioatmictouchsms
  • sms_from_numberstringnullableoptional
    Sending number. Required (with sms_carrier) for the campaign to be startable.
  • sms_rate_per_minuteinteger1–600optional
    Send throttle, messages per minute.
    Default 60
  • recipientsobject[]required
    Contacts to message. At least one is required.
    6 fields
    • phone_numberstring1–∞ charsrequired
    • first_namestringnullableoptional
    • last_namestringnullableoptional
    • emailstringnullableoptional
    • companystringnullableoptional
    • custom_variablesobjectoptional
      Default {}
  • csv_column_headersstring[]optional
    Default []
  • schedule_typestringoptional
    Default "immediate"
    immediatescheduled
  • scheduled_start_atstringnullableoptional
  • scheduled_expires_atstringnullableoptional
  • business_hours_configobjectnullableoptional
  • holidays_configobjectnullableoptional

Response 201 Created

Created. Includes sms_opted_out_excluded.

  • idstringoptional
    Stable UUID of the campaign.
  • workspace_idstringoptional
    UUID of the owning workspace.
  • agent_idstringnullableoptional
    UUID of the agent that places calls for this campaign.
  • namestringoptional
    Human-readable campaign name. 1-255 chars.
  • descriptionstringnullableoptional
    Optional free-form notes.
  • statusstringnullableoptional
    Raw DB status. One of draft, ready, scheduled, active, paused, completed, cancelled, expired. Prefer effective_status for UI display.
  • effective_statusstringnullableoptional
    User-visible status. Equals status except when the campaign has a non-terminal status and scheduled_expires_at has passed — then expired is returned. Possible values: draft, ready, scheduled, active, paused, completed, cancelled, expired.
  • schedule_typestringnullableoptional
    One of immediate (start when activated) or scheduled (wait for scheduled_start_at).
  • scheduled_start_atstringnullableoptional
    ISO 8601 UTC timestamp the campaign is scheduled to start. Null for immediate campaigns.
  • scheduled_expires_atstringnullableoptional
    ISO 8601 UTC timestamp after which the campaign is considered expired. Null = no expiry.
  • business_hours_onlybooleannullableoptional
    When true, calls only place within business_hours_config. See CampaignCreate for the config shape.
  • timezonestringnullableoptional
    IANA Time Zone for business-hours evaluation (e.g. America/New_York, Australia/Melbourne).
  • total_recipientsintegernullableoptional
    Count of recipients loaded into the campaign.
  • pending_callsintegernullableoptional
    Recipients not yet called.
  • completed_callsintegernullableoptional
    Recipients whose call lifecycle finished (any outcome).
  • successful_callsintegernullableoptional
    Calls where the recipient answered and the analyser marked a positive outcome.
  • failed_callsintegernullableoptional
    Calls that exhausted retries without a positive outcome (busy, no-answer, declined, etc.).
  • created_atstringnullableoptional
    ISO 8601 UTC timestamp when the campaign was created.
  • updated_atstringnullableoptional
    ISO 8601 UTC timestamp of the last update.
  • started_atstringnullableoptional
    ISO 8601 UTC timestamp the campaign first transitioned to active.
  • completed_atstringnullableoptional
    ISO 8601 UTC timestamp the campaign reached a terminal state. Null while in progress.
  • channelstringnullableoptional
    call (default) or sms. Determines which engine runs the campaign; SMS campaigns carry the sms_* fields below.
  • business_hours_configobjectnullableoptional
    Resolved business-hours config as stored — always in the {enabled, timezone, schedule, batchConcurrency} form, with schedule keyed by full day names holding arrays of windows. A days-shaped request body is normalised into this on write.
  • holidays_configobjectnullableoptional
    Holiday calendar ({country, holidays[]}) — dialling is skipped on enabled dates.
  • batch_concurrencyintegernullableoptional
    Recipients dispatched per batch wave (1-40).
  • sip_trunk_idstringnullableoptional
    UUID of the SIP trunk this campaign dials over. Null = provider default routing.
  • cli_modestringnullableoptional
    default (single agent-derived caller ID) or group (rotate across the numbers in cli_group_config).
  • cli_group_configobject[]nullableoptional
    Caller-ID rotation spec used when cli_mode=group. Each entry allocates count recipients to one number on the trunk.
    3 fields
    • phoneNumberIdstringoptional
    • phoneE164stringoptional
    • countintegeroptional
  • ivr_enabledbooleannullableoptional
    When true, outbound calls carry IVR-navigation metadata to the provider.
  • call_screen_enabledbooleannullableoptional
    When true, outbound calls are sent with call-screening handling enabled.
  • double_dialbooleannullableoptional
    When true, an unanswered number is dialled a second time immediately.
  • csv_column_headersstring[]nullableoptional
    Column headers of the source import, retained for display and mapping.
  • sms_modestringnullableoptional
    SMS campaigns only. one_way or conversational.
  • sms_message_sourcestringnullableoptional
    SMS campaigns only. custom (uses sms_message_body) or flow (uses sms_flow_id).
  • sms_message_bodystringnullableoptional
    SMS campaigns only. The composed message template.
  • sms_flow_idstringnullableoptional
    SMS campaigns only. UUID of the Automations flow that drives the campaign.
  • sms_carrierstringnullableoptional
    SMS campaigns only. twilio, atmic or touchsms.
  • sms_from_numberstringnullableoptional
    SMS campaigns only. Sending number.
  • sms_rate_per_minuteintegernullableoptional
    SMS campaigns only. Send throttle, 1-600 messages per minute.
  • agentobjectoptional
    Compact snapshot of the assigned agent (id, name, provider, is_active). Read-only.
    4 fields
    • idstringoptional
    • namestringoptional
    • providerstringoptional
    • is_activebooleanoptional
  • sms_opted_out_excludedintegeroptional
    Number of supplied contacts dropped because they are on the workspace's unsubscribe register. Those contacts were never written as recipients.

Errors

  • 400Bad Request
    Validation failed / malformed request.
  • 401Unauthorized
    Missing, malformed, or invalid API key.
  • 403Forbidden
    Workspace unavailable, suspended, or paywalled.
  • 429Too Many Requests
    Workspace request limit exceeded; shared across all its API keys.