Bulk vs Transactional vs Direct

Transformify supports three sending patterns: bulk (promotional), transactional, and direct send.

Bulk / Promotional

Bulk sends deliver messages to many recipients at once. Use for:

• Marketing campaigns
• Announcements
• Promotional offers
• Newsletters

How It Works

1. Call the bulk endpoint with a template and recipients — returns 202 immediately
2. A campaign is created with Queuing status while messages are prepared in the background
3. Poll GET /api/v1/campaigns/{id} until status reaches Ready
4. Call POST /api/v1/campaigns/{id}/start to begin delivery
5. Campaign moves to InProgress and completes when all messages are processed

SMS Promotional

curl -X POST https://api.transformify.mk/api/v1/sms/promotional \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "template-id",
    "recipients": [
      {
        "phoneNumber": "38970111111",
        "placeholders": { "name": "John", "promoCode": "JOHN20" }
      },
      {
        "phoneNumber": "38970222222",
        "placeholders": { "name": "Jane", "promoCode": "JANE20" }
      },
      {
        "phoneNumber": "38970333333",
        "placeholders": { "name": "Bob", "promoCode": "BOB20" }
      }
    ]
  }'

Viber Bulk

curl -X POST https://api.transformify.mk/api/v1/viber/send \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "viber-template-id",
    "recipients": [
      {
        "phoneNumber": "38970111111",
        "placeholders": { "name": "John" }
      },
      {
        "phoneNumber": "38970222222",
        "placeholders": { "name": "Jane" }
      }
    ]
  }'

Characteristics

Feature	Bulk
Recipients	Many at once
Channels	SMS (/sms/promotional) or Viber (/viber/send)
Placeholders	Per-recipient (with optional request-level fallback)
Lifecycle	Queuing → Ready → start manually → InProgress → Completed
Use case	Marketing, announcements, batch notifications

---

Transactional

Transactional campaigns send individual messages in real-time via SMS or Viber. Use for:

• OTP codes
• Order confirmations
• Delivery updates
• Appointment reminders
• Any event-triggered message

How It Works

1. Create a campaign with POST /api/v1/sms/campaigns or POST /api/v1/viber/campaigns
2. Campaign stays open (InProgress status)
3. Add messages one at a time with POST /api/v1/{channel}/campaigns/{id}/messages
4. Each message is processed immediately

SMS Example

Step 1: Create Campaign (once)

curl -X POST https://api.transformify.mk/api/v1/sms/campaigns \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Notifications",
    "description": "Transactional campaign for order status updates",
    "templateId": "sms-template-id"
  }'

Step 2: Add Messages (on each event)

curl -X POST https://api.transformify.mk/api/v1/sms/campaigns/{campaignId}/messages \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "38970123456",
    "externalUserId": "order_12345",
    "placeholders": {
      "orderId": "ORD-12345",
      "status": "shipped",
      "trackingNumber": "1Z999AA10123456784"
    }
  }'

Viber Example

Step 1: Create Campaign (once)

curl -X POST https://api.transformify.mk/api/v1/viber/campaigns \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Reminders",
    "templateId": "viber-template-id"
  }'

Step 2: Add Messages (on each event)

curl -X POST https://api.transformify.mk/api/v1/viber/campaigns/{campaignId}/messages \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "38970123456",
    "externalUserId": "appointment_789",
    "placeholders": {
      "name": "John",
      "appointmentDate": "2024-01-20"
    }
  }'

Characteristics

Feature	Transactional
Recipients	One at a time
Channels	SMS (/sms/campaigns) and Viber (/viber/campaigns)
Placeholders	Unique per message
Lifecycle	Campaign stays open indefinitely
Use case	Event-driven notifications

---

---

Direct Send

Direct send lets you fire off messages without creating templates or managing campaigns. Just provide message content, a sender/service ID, and recipients.

How It Works

1. Call POST /api/v1/sms/send or POST /api/v1/viber/send-text with raw message content and recipients
2. Messages are queued for immediate processing

SMS Example

curl -X POST https://api.transformify.mk/api/v1/sms/send \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messageContent": "Your order #12345 has been shipped!",
    "smsSenderId": 1,
    "recipients": [
      { "phoneNumber": "38970123456" },
      { "phoneNumber": "38970123457" }
    ]
  }'

Viber Example

curl -X POST https://api.transformify.mk/api/v1/viber/send-text \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messageContent": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "viberServiceId": 1,
    "recipients": [
      { "phoneNumber": "38970123456" },
      { "phoneNumber": "38970123457" }
    ]
  }'

Characteristics

Feature	Direct Send
Recipients	Multiple per request
Channels	SMS (/sms/send) and Viber (/viber/send-text)
Templates	Not required — raw message content
Placeholders	Not supported
Campaign management	Automatic (hidden)
Use case	Quick sends, simple notifications

---

Comparison

Aspect	Bulk / Promotional	Transactional	Direct Send
API	POST /sms/promotional or POST /viber/send	POST /sms/campaigns + messages, POST /viber/campaigns + messages	POST /sms/send or POST /viber/send-text
Channels	SMS and Viber	SMS and Viber	SMS and Viber
Recipients	Many at once	One per request	Multiple per request
Template	Required	Required	Not needed
Personalization	Per-recipient placeholders	Unique per message	None (same content for all)
Timing	Async — poll for Ready, then start	Immediate	Immediate
Campaign lifecycle	Queuing → Ready → start → Completed	Stays open	Automatic (hidden)
Best for	Marketing, batch notifications	Event-driven notifications	Quick sends, simple notifications

---

When to Use Each

Use Bulk When:

• Sending messages to many people at once
• Running a marketing campaign
• Making an announcement
• You have all recipient data available upfront
• Sending via either SMS or Viber

Use Transactional When:

• Messages are triggered by events (orders, signups, etc.)
• Each message needs unique content via template placeholders
• Real-time delivery is important
• You need to send messages over an extended period
• Sending via SMS or Viber

Use Direct Send When:

• You want the simplest integration — no template setup required
• Sending the same message to a batch of recipients
• Quick notifications that don't need placeholder personalization
• Sending via SMS or Viber (simple text only for Viber)