רוב האינטגרציות משתמשות ב-API כדי לסנכרן נמענים: הוספת נמענים חדשים לקבוצות, עדכון הפרטים והסטטוס שלהם, והסרה שלהם. המדריך הזה מציג את הקריאות הבסיסיות. לכל הפרמטרים, ראו API reference: contacts ו-API reference: groups.
לפני שמתחילים, ודאו שאתם יודעים לבצע קריאות API בסיסיות. ראו תחילת העבודה עם ה-API של אקטיב טרייל.
חיפוש נמען
נמענים מזוהים לפי מזהה הנמען (contact ID). כדי למצוא נמען לפי כתובת מייל או מספר נייד, חפשו ברשימת הנמענים:
GET https://webapi.mymarketing.co.il/api/contacts?SearchTerm=dana@example.com
קחו את ה-id מהתשובה, ואז קבלו את כל פרטי הנמען:
GET https://webapi.mymarketing.co.il/api/contacts/{id}
תשובת 404 פירושה שהנמען לא קיים בחשבון שלכם. אין תמיכה בחיפוש כתובות מייל שיש בהן סימן פלוס (+); ראו חיפוש ב-API וסימן הפלוס (+).
כדי לקבל את סטטוס המייל ואת סטטוס ה-SMS של נמען בקריאה אחת, חפשו עם GET https://webapi.mymarketing.co.il/api/contacts/GetWithSmsState?SearchTerm=dana@example.com. כל נמען מוחזר עם state (סטטוס המייל) ועם sms_state. אם אין התאמה, התשובה היא רשימה ריקה.
הוספת נמען לקבוצה
כדי להוסיף נמען ולשייך אותו לקבוצה בקריאה אחת, שלחו בקשת POST לנקודת הקצה של חברי הקבוצה. אפשר גם לקבוע את סטטוס המייל וה-SMS של הנמען:
POST https://webapi.mymarketing.co.il/api/groups/{id}/members
{
"email": "dana@example.com",
"sms": "0501234567",
"first_name": "Dana",
"last_name": "Levi",
"status": "Subscribed",
"sms_status": "Subscribed"
}
ערכי הסטטוס הם Subscribed, Unsubscribed ו-Pending. נמען שלא פעיל באקטיב טרייל לא יכול להתווסף עם הסטטוס Subscribed.
POST /api/contacts יוצר גם הוא נמען, אבל לא מוסיף אותו לאף קבוצה, ולכן אי אפשר לשלוח אליו מייל או SMS עד שהוא נמצא בקבוצה. כדי להוסיף נמען חדש שתרצו לשלוח אליו הודעות, השתמשו בנקודת הקצה של חברי הקבוצה שלמעלה.
כדי להוסיף הרבה נמענים בבת אחת, השתמשו ב-POST /api/contacts/Import, עד 1,000 נמענים בכל קריאה.
עדכון נמען
שלחו בקשת PUT רק עם השדות שתרצו לשנות. לדוגמה, כדי להסיר נמען מדיוור במייל:
PUT https://webapi.mymarketing.co.il/api/contacts/{id}
{
"status": "Unsubscribed"
}
הוצאת נמען מקבוצה
DELETE https://webapi.mymarketing.co.il/api/groups/{id}/members/{memberId}
הקריאה הזו מוציאה את הנמען מהקבוצה בלבד. הנמען נשאר בחשבון שלכם.
מחיקת נמען
מחיקת נמען מוחקת גם את הסטטיסטיקה שלו, ולכן מומלץ להסיר נמענים מדיוור במקום למחוק אותם. אם בכל זאת צריך למחוק נמען:
DELETE https://webapi.mymarketing.co.il/api/contacts/{id}
יצירה או עדכון בסנכרון
בתהליכים שמסנכרנים נמענים באופן קבוע ממערכת אחרת:
- אם הנתונים משתנים לאט, נסו קודם לעדכן את הנמען, וצרו אותו רק אם העדכון נכשל.
- בייבוא גדול, צרו קודם את הנמענים, ועדכנו רק את אלה שכבר קיימים.