למפתחים · API Reference

Campaigns API — שליחת תפוצות ממערכות אחרות

שליחת תפוצות מייל ווואטסאפ מ-TaskFlow ישירות מה-CRM, האתר, ה-ERP או כל מערכת אחרת: יצירה, עיצוב מייל עם AI, שליחת בדיקה, שליחה מיידית או מתוזמנת, מעקב אחרי מסירה ופתיחות, השהיה וביטול.

תוכן העניינים

1. אימות והרשאות
2. התהליך בקצרה
3. GET /campaigns/senders — שולחים ותבניות
4. POST /campaigns — יצירה (ושליחה)
5. תפוצת מייל — HTML, טקסט או עיצוב AI
6. תפוצת וואטסאפ — תבנית מאושרת
7. נמענים — רשימה או טבלה עם סינון
8. POST /campaigns/{id}/test — בדיקה
9. POST /campaigns/{id}/send — שליחה ותזמון
10. GET /campaigns/{id} — סטטוס וסטטיסטיקות
11. השהיה / המשך / ביטול
12. GET /campaigns — רשימה
13. POST /email/design — עיצוב מייל בלבד
14. שדות מיזוג והסרה מרשימה
15. שגיאות ומגבלות
16. דוגמאות מלאות (Node / Python / PHP)

1. אימות והרשאות

יוצרים מפתח ב-מפתחות API. כל בקשה נשלחת עם header:

Authorization: Bearer acb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• קריאה (can_read) — רשימות, סטטוס, שולחים.
• יצירה (can_create) — יצירה, בדיקה, שליחה, השהיה וביטול.
• אם המפתח מוגבל לטבלאות מסוימות — אפשר לשלוח רק לנמענים מהטבלאות האלה.

Base URL: https://taskflow-ai.com/api/v1 · כל הבקשות וההחזרות ב-JSON.

2. התהליך בקצרה

1. GET /campaigns/senders — מוודאים שיש כתובת שליחה מאומתת (מייל) או תבנית מאושרת (וואטסאפ).
2. POST /campaigns — יוצרים טיוטה עם תוכן ונמענים.
3. POST /campaigns/{id}/test — שולחים בדיקה לעצמכם (מומלץ).
4. POST /campaigns/{id}/send — שולחים עכשיו או מתזמנים.
5. GET /campaigns/{id} — עוקבים אחרי שליחה, מסירה ופתיחות.

אפשר גם בצעד אחד: POST /campaigns עם "send_at": "now".

3. GET /campaigns/senders

מה אפשר לשלוח ממנו: כתובות מייל (רק ready: true שולחות) ותבניות וואטסאפ עם מספר המשתנים בכל אחת.

curl https://taskflow-ai.com/api/v1/campaigns/senders -H "Authorization: Bearer $TF_KEY"

{
  "email": [
    { "id": "8b1c…", "from_email": "info@mybiz.co.il", "from_name": "My Biz", "type": "taskflow", "ready": true }
  ],
  "whatsapp": {
    "connected": true,
    "number": "+972 50-123-4567",
    "templates": [
      { "name": "sale_weekend", "language": "he", "status": "APPROVED", "category": "MARKETING",
        "body": "שלום {{1}}, סוף שבוע של {{2}} הנחה…", "variables": 2 }
    ]
  }
}

אין כתובת מייל מוכנה? מייל יוצא רק מדומיין של העסק — מחברים או קונים דומיין במסך התפוצות. אין תבנית מאושרת? יוצרים ושולחים לאישור Meta במסך תבניות וואטסאפ.

4. POST /campaigns — יצירה

תגובה 201:

{
  "campaign": {
    "id": "5f0e…", "name": "מבצע סוף שבוע", "channel": "email", "status": "draft",
    "subject": "20% הנחה עד מוצ״ש", "total_recipients": 0, "sent_count": 0, "failed_count": 0,
    "scheduled_at": null, "created_at": "2026-10-06T16:20:00Z", "finished_at": null, "last_error": null
  },
  "audience": 1240
}

audience = מספר הנמענים התקינים כרגע (אחרי ניקוי כפולים, כתובות לא תקינות ומי שביקש הסרה).

5. תפוצת מייל

שלוש דרכים לתוכן — בוחרים אחת:

curl -X POST https://taskflow-ai.com/api/v1/campaigns \
  -H "Authorization: Bearer $TF_KEY" -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "name": "מבצע סוף שבוע",
    "email": {
      "ai": { "prompt": "מבצע 20% על כל החנות עד מוצאי שבת, קוד קופון SALE20", "style": "bold", "brand_color": "#E11D48", "cta_url": "https://mybiz.co.il/shop" }
    },
    "recipients": { "table_id": "TABLE_ID", "filters": [ { "field_slug": "status", "operator": "equals", "value": "לקוח" } ] }
  }'

עם HTML משלכם ושליחה מיידית:

{
  "channel": "email",
  "email": { "subject": "העדכון החודשי", "html": "<!doctype html><html dir=\"rtl\">…</html>" },
  "recipients": { "emails": ["dana@example.com", "yossi@example.com"] },
  "send_at": "now"
}

6. תפוצת וואטסאפ

תפוצת וואטסאפ נשלחת רק דרך מספר WhatsApp Cloud (Meta) ורק עם תבנית מאושרת — זו דרישה של Meta. הודעה בודדת ללקוח בתוך חלון שיחה פתוח שולחים ב-POST /messages (API Reference), לא כתפוצה.

curl -X POST https://taskflow-ai.com/api/v1/campaigns \
  -H "Authorization: Bearer $TF_KEY" -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "whatsapp": { "template_name": "sale_weekend", "language": "he", "variables": ["לקוח יקר", "20%"] },
    "recipients": { "phones": ["0501234567", "972521234567"] },
    "send_at": "2026-10-07T10:00:00+03:00"
  }'

מספרים מתקבלים בכל פורמט ישראלי (050-1234567, 0501234567, 972501234567).

7. נמענים

אופרטורים: equals, not_equals, contains, is_any_of (value = מערך), is_empty, is_not_empty, greater_than, less_than, is_in_last_days (value = מספר ימים), is_this_month.

"recipients": {
  "table_id": "TABLE_ID",
  "field_slug": "email",
  "filters": [
    { "field_slug": "city", "operator": "is_any_of", "value": ["תל אביב", "רמת גן"] },
    { "field_slug": "created_at", "operator": "is_in_last_days", "value": 90 }
  ]
}

לפני כל שליחה המערכת מסירה כפולים, כתובות לא תקינות, דומיינים מתים ומי שביקש הסרה או שהמייל אליו חזר.

8. POST /campaigns/{id}/test

שולח עותק אחד (במייל עם "[בדיקה]" בנושא). מייל → כתובת, וואטסאפ → מספר.

curl -X POST https://taskflow-ai.com/api/v1/campaigns/CAMPAIGN_ID/test \
  -H "Authorization: Bearer $TF_KEY" -H "Content-Type: application/json" \
  -d '{ "to": "me@mybiz.co.il" }'

9. POST /campaigns/{id}/send

לפני שליחת מייל רצה בדיקה מוקדמת (אותה בדיקה כמו בכפתור "שלח" בלוח הבקרה):

• 202 — נכנס לתור / תוזמן.
• 409 needs_confirmation — יש אזהרות (למשל: לא נשלחה בדיקה, אין כתובת להשבה, חלק מהנמענים סוננו). קוראים את warnings ושולחים שוב עם "confirm": true.
• 422 preflight_blocked — אי אפשר לשלוח (למשל: הדומיין לא מאומת, אין נמענים תקינים, נגמרה חבילת המיילים). הפירוט ב-blocks.

// 409
{ "error": "needs_confirmation",
  "warnings": [ { "code": "no_test", "level": "warn", "message": "לא נשלח מייל בדיקה לטיוטה הזו" } ] }

10. GET /campaigns/{id}

סטטוס וספירות. ?recipients=1 מוסיף עד 1,000 שורות נמענים.

{
  "campaign": { "id": "5f0e…", "status": "sending", "sent_count": 812, "failed_count": 3, … },
  "stats": { "total": 1240, "sent": 812, "failed": 3, "pending": 425, "delivered": 790, "opened": 301, "clicked": 44 }
}

סטטוסים: draft · scheduled · sending · paused · completed · failed · cancelled. מומלץ לבדוק כל דקה-שתיים עד completed.

בוואטסאפ opened = נקרא (V כחול). במייל הפתיחות נמדדות בפיקסל, וחלק מתוכנות המייל חוסמות אותו.

11. השהיה / המשך / ביטול

POST https://taskflow-ai.com/api/v1/campaigns/CAMPAIGN_ID/pause    # עוצר אחרי ההודעה הנוכחית
POST https://taskflow-ai.com/api/v1/campaigns/CAMPAIGN_ID/resume   # ממשיך מאיפה שעצר
POST https://taskflow-ai.com/api/v1/campaigns/CAMPAIGN_ID/cancel   # מבטל; מי שעוד לא קיבל — לא יקבל

12. GET /campaigns

פרמטרים: status, channel (email / whatsapp), limit (עד 100).

curl "https://taskflow-ai.com/api/v1/campaigns?channel=email&status=completed&limit=10" -H "Authorization: Bearer $TF_KEY"

13. POST /email/design — עיצוב מייל בלבד

מקבלים HTML מעוצב בלי ליצור תפוצה — למשל כדי לשלוח דרך מערכת אחרת או להציג תצוגה מקדימה.

{ "subject": "20% הנחה עד מוצ״ש", "preheader": "…", "html": "<!doctype html>…", "spec": { … } }

14. שדות מיזוג והסרה מרשימה

• בנושא ובגוף המייל אפשר {{first_name}}, {{name}} או כל slug של עמודה בטבלה, עם ברירת מחדל: {{first_name|לקוח יקר}}.
• {{unsubscribe_url}} = קישור הסרה אישי. אם אין אותו ב-HTML, שורת הסרה נוספת אוטומטית בתחתית. מי שהוסר לא יקבל יותר מיילים מהסביבה.
• במיילים שנשלחים נוסף גם header List-Unsubscribe.

15. שגיאות ומגבלות

• מכסת שליחה לשעה — נקבעת ב"בקרת שליחה" במסך התפוצות; תפוצה גדולה ממשיכה אוטומטית בשעה הבאה.
• חבילת מיילים — אם לסביבה יש חבילה, כל מייל שנשלח יורד ממנה; בסיום החבילה התפוצה נעצרת עם הודעה.
• וואטסאפ — Meta מחייבת על כל הודעת תבנית לפי הקטגוריה (שיווק / שירות); המגבלה היומית תלויה בדירוג המספר.
• כל קריאה נרשמת ביומן המפתח (מסך מפתחות API).

16. דוגמאות מלאות

Node.js — יצירה, בדיקה, שליחה ומעקב

const API = 'https://taskflow-ai.com/api/v1';
const H = { Authorization: `Bearer ${process.env.TF_KEY}`, 'Content-Type': 'application/json' };

async function call(method, path, body) {
  const r = await fetch(API + path, { method, headers: H, body: body ? JSON.stringify(body) : undefined });
  const j = await r.json();
  if (!r.ok && r.status !== 409) throw new Error(`${r.status} ${j.error}: ${j.message || ''}`);
  return { status: r.status, ...j };
}

// 1. create
const { campaign, audience } = await call('POST', '/campaigns', {
  channel: 'email',
  email: { ai: { prompt: 'הזמנה לערב השקה ביום חמישי ב-19:00, מספר המקומות מוגבל', style: 'warm' } },
  recipients: { table_id: process.env.TF_TABLE, filters: [{ field_slug: 'status', operator: 'equals', value: 'לקוח' }] },
});
console.log('created', campaign.id, 'audience', audience);

// 2. test
await call('POST', `/campaigns/${campaign.id}/test`, { to: 'me@mybiz.co.il' });

// 3. send (accept warnings after review)
let res = await call('POST', `/campaigns/${campaign.id}/send`, { send_at: 'now' });
if (res.status === 409) {
  console.log('warnings:', res.warnings.map(w => w.message));
  res = await call('POST', `/campaigns/${campaign.id}/send`, { send_at: 'now', confirm: true });
}

// 4. poll
for (;;) {
  const { campaign: c, stats } = await call('GET', `/campaigns/${campaign.id}`);
  console.log(c.status, stats);
  if (['completed', 'failed', 'cancelled'].includes(c.status)) break;
  await new Promise(r => setTimeout(r, 60_000));
}

Python — וואטסאפ מתוזמן

import os, requests
API = 'https://taskflow-ai.com/api/v1'
H = {'Authorization': f"Bearer {os.environ['TF_KEY']}"}

r = requests.post(f'{API}/campaigns', headers=H, json={
    'channel': 'whatsapp',
    'whatsapp': {'template_name': 'appointment_reminder', 'variables': ['מחר', '10:00']},
    'recipients': {'phones': ['0501234567', '0527654321']},
    'send_at': '2026-10-07T08:00:00+03:00',
})
print(r.status_code, r.json())

PHP — מייל מ-HTML קיים

<?php
$ch = curl_init('https://taskflow-ai.com/api/v1/campaigns');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('TF_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'channel' => 'email',
    'email' => ['subject' => 'החשבונית החודשית מוכנה', 'html' => file_get_contents('newsletter.html')],
    'recipients' => ['emails' => ['dana@example.com']],
    'send_at' => 'now',
    'confirm' => true,
  ], JSON_UNESCAPED_UNICODE),
]);
echo curl_exec($ch);