REST API endpoints for campaign management

Campaigns are the primary way to send bulk outbound SMS or MMS messages to an audience in Amplifi. Each campaign targets an audience defined by a saved segment (segmentId) or an ad-hoc contact filter (contactFilter), and carries a message body plus optional media URL for MMS. Campaigns move through a lifecycle of statuses—from draft to completed—and can be scheduled for a future time or sent immediately.

Campaign statuses

Status	Description
`draft`	Being composed; not yet submitted for sending.
`scheduled`	Approved and queued to send at `scheduledFor`.
`pending`	Submitted for sending; awaiting queue admission.
`queued`	Admitted to the send queue; messages being generated.
`sending`	Messages actively being dispatched.
`completed`	All messages sent or failed; no further processing.
`failed`	The campaign failed to start or encountered a fatal error.
`paused`	Sending paused mid-campaign; can be resumed.

List campaigns

GET /api/campaigns

Returns all campaigns for your organization ordered by creation date descending. Each campaign in the list includes summary metrics (sent count, failed count, delivery rate) computed at query time.

Response

[
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "name": "April Fundraiser Blast",
    "status": "completed",
    "channel": "text",
    "scheduledFor": null,
    "timezone": null,
    "totalCount": 4200,
    "sentCount": 4187,
    "failedCount": 13,
    "queuedCount": 0,
    "deliveryRate": 100,
    "replyCountExcludingOptouts": 312,
    "message": "Hi {{firstName}}, join us April 28 for our annual fundraiser! Reply STOP to opt out.",
    "mediaUrl": null,
    "createdAt": "2025-04-20T13:00:00.000Z",
    "updatedAt": "2025-04-20T15:43:00.000Z",
    "completedAt": "2025-04-20T15:43:00.000Z"
  }
]

Create a campaign

POST /api/campaigns

Creates and immediately submits a campaign for sending (or schedules it if scheduledFor is provided). You must supply either segmentId or contactFilter to define the audience, but not both.

To save a campaign as a draft without sending, use POST /api/campaigns/draft instead.

Request body

name

string

required

Display name for the campaign (e.g. "April Fundraiser Blast").

message

string

required

The message body to send. Supports merge fields: {{firstName}}, {{lastName}}, {{email}}, {{phone}}, {{city}}, {{state}}, {{zip}}, and any custom fields.

segmentId

string (UUID)

UUID of a saved segment to use as the audience. Mutually exclusive with contactFilter.

contactFilter

object

Ad-hoc filter defining the audience. Mutually exclusive with segmentId. Common structure: { "tags": ["vip"], "tagsLogic": "AND" }.

fromPhoneNumberId

string (UUID)

UUID of the phone number to send from. Defaults to your organization’s default phone number.

scheduledFor

string (ISO 8601 datetime)

When to send the campaign. If omitted or in the past, the campaign is sent immediately. Must be in UTC.

timezone

string

IANA timezone string for display purposes (e.g. America/New_York). Quiet hours (8 AM–9 PM) are enforced in this timezone.

mediaUrl

string

Public URL of media to attach. When present, the campaign is sent as MMS regardless of forceRoute.

forceRoute

string

Override automatic SMS/MMS routing. AUTO (default), SMS, or MMS.

channel

string

Channel type. Currently text is the only supported value.

normalizeText

boolean

When true (default), smart quotes and other Unicode characters are normalized to ASCII to avoid multi-segment messages.

isAbTest

boolean

Enable A/B testing. When true, you must provide messageVariantA and messageVariantB.

messageVariantA

string

Message body for A/B test variant A (sent to a 5% sample).

messageVariantB

string

Message body for A/B test variant B (sent to a 5% sample).

autoReplyEnabled

boolean

Enable automatic replies to inbound responses. When true, configure yesResponse, noResponse, or faqReplies.

yesResponse

string

Auto-reply message when a contact replies with an affirmative response.

noResponse

string

Auto-reply message when a contact replies with a negative response.

faqReplies

object[]

Up to 5 FAQ reply pairs. Each object: { "question": "string", "answer": "string" }.

draftId

string (UUID)

UUID of an existing draft campaign to promote to a live campaign. The draft is updated in place rather than creating a new record.

Example request

{
  "name": "April Fundraiser Blast",
  "message": "Hi {{firstName}}, join us April 28 for our annual fundraiser. RSVP at https://example.com/rsvp — Reply STOP to opt out.",
  "segmentId": "c3d4e5f6-a7b8-9012-cdef-234567890123",
  "scheduledFor": "2025-04-28T13:00:00.000Z",
  "timezone": "America/New_York",
  "autoReplyEnabled": true,
  "yesResponse": "Great, we'll see you there!",
  "noResponse": "No worries, we'll keep you updated."
}

Response

Returns the created campaign object with status 201.

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "name": "April Fundraiser Blast",
  "status": "scheduled",
  "channel": "text",
  "message": "Hi {{firstName}}, join us April 28...",
  "mediaUrl": null,
  "segmentId": "c3d4e5f6-a7b8-9012-cdef-234567890123",
  "contactFilter": null,
  "scheduledFor": "2025-04-28T13:00:00.000Z",
  "timezone": "America/New_York",
  "totalCount": 0,
  "sentCount": 0,
  "failedCount": 0,
  "queuedCount": 0,
  "forceRoute": "AUTO",
  "normalizeText": true,
  "isAbTest": false,
  "autoReplyEnabled": true,
  "createdAt": "2025-04-24T10:15:00.000Z",
  "updatedAt": "2025-04-24T10:15:00.000Z"
}

Get a campaign

GET /api/campaigns/:id

Returns the full campaign record including real-time delivery metrics and the associated sending phone number.

Path parameters

string (UUID)

required

The campaign’s UUID.

Response

In addition to all campaign fields, the response includes:

phoneNumber

object | null

Details of the phone number used to send the campaign, or null if not yet assigned.

displayMetrics

object

Computed display metrics including audience size, sent/failed/queued counts, and delivery rate.

Update a draft campaign

PUT /api/campaigns/:id/draft

Updates a campaign that has status: "draft". All fields from the campaign draft schema are accepted and are optional—send only those you want to change. Returns 400 if the campaign is not in draft status.

Path parameters

string (UUID)

required

UUID of the draft campaign to update.

Send a campaign immediately

POST /api/campaigns/:id/test-send

Sends a test copy of the campaign to a specified list of phone numbers without affecting the campaign’s audience or metrics. Useful for previewing message rendering with actual merge fields.

To trigger production sending of a campaign that is in draft status, use POST /api/campaigns with draftId set to the draft’s UUID.

Request body

recipients

string[]

required

Array of E.164 phone numbers to receive the test message.

body

string

Message body to send. Defaults to the campaign’s current message.

mediaUrls

string[]

Media URLs for MMS test sends.

fromPhoneNumberId

string (UUID)

Override the sending phone number for this test.

mergePreviewData

object

Key-value pairs substituted into merge fields for the preview (e.g. { "firstName": "Alex" }).

Key fields reference

forceRoute

string

AUTO, SMS, or MMS. Controls how message routing is decided. AUTO sends as MMS only when mediaUrl is present or the message contains characters that require it.

normalizeText

boolean

When true, smart quotes, em dashes, and other non-ASCII characters are replaced with their ASCII equivalents before sending to maximize message segment efficiency.

sentCount

number

Number of messages that have been dispatched to the carrier. Does not indicate delivery confirmation.

failedCount

number

Number of messages that failed to send, including carrier rejections and invalid numbers.

replyCountExcludingOptouts

number

Count of inbound replies received after the campaign started, excluding opt-out messages.

Campaigns cannot be sent outside of quiet hours (8 AM–9 PM in the campaign’s timezone). Attempting to send outside this window will return an error. Schedule campaigns in advance to avoid unexpected failures.

API

Configuration

Documentation Index

​Campaign statuses

​List campaigns

​Response

​Create a campaign

​Request body

​Example request

​Response

​Get a campaign

​Path parameters

​Response

​Update a draft campaign

​Path parameters

​Send a campaign immediately

​Request body

​Key fields reference

Campaign statuses

List campaigns

Response

Create a campaign

Request body

Example request

Response

Get a campaign

Path parameters

Response

Update a draft campaign

Path parameters

Send a campaign immediately

Request body

Key fields reference