מדריך REST API של Email Verifier

ה-API של Email Verifier זמין תחת /api/v1. יש להשתמש במארח TrekMail שבו החשבון נכנס למערכת. הדוגמאות משתמשות ב-https://YOUR-TREKMAIL-HOST כמציין מקום.

אימות זהות ו-scopes

יש להעביר אסימון API בכותרת Authorization:

Authorization: Bearer YOUR_API_TOKEN

יש להפעיל scopes בעת יצירת האסימון:

יש להעניק ללקוח את שני ה-scopes אם עליו לשלוח עבודה ולאחר מכן לקרוא או להוריד את התוצאה.

מארח ומבנה הבקשה

כל הדוגמאות משתמשות בגופי בקשת JSON ובאסימון Bearer. העלאת הקבצים בלוח הבקרה נפרדת מה-API: הבקשה POST /verify/bulk מקבלת מערך JSON בשם emails, ולא קובץ multipart. יש להשתמש בדיוק במארח ששייך לחשבון ולאסימון. אין להניח שאסימון או יתרה ממארח ממותג אחד יעבדו במארח אחר.

יש לשלוח Content-Type: application/json בבקשות POST /verify ו-POST /verify/bulk. יש לשמור את האסימון ואת ערך האידמפוטנטיות מחוץ לקוד בצד הלקוח.

אידמפוטנטיות

הבקשות POST /api/v1/verify/bulk ו-DELETE /api/v1/verify/bulk/{jobId} דורשות את הכותרת Idempotency-Key. יש ליצור ערך חדש לכל פעולה מכוונת ולהשתמש בו שוב רק כשמנסים מחדש את אותה פעולה.

Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee

אימות יחיד וביטול משימה אינם דורשים כותרת זו. בקשה בכמות גדולה מוגנת גם באמצעות זיהוי אותה רשימה מנורמלת ואותו מצב בתוך 24 שעות, אך מפתח אידמפוטנטיות הוא עדיין המנגנון הנכון לניסיון חוזר.

טיפול בתוצאת רשת לא ודאית

אם היישום מאבד את התגובה לבקשה בכמות גדולה, אין ליצור מפתח חדש ולשלוח רשימה נוספת. יש לחזור על הבקשה הזהה עם אותו מפתח. שמרו את המפתח יחד עם מזהה רשימת המקור עד ש-TrekMail יחזיר מזהה משימה. כך הניסיון החוזר נשאר מחובר לפעולה המקורית ואינו יוצר חיוב שני שניתן למנוע.

סיכום נקודות הקצה

יש להוסיף /api/v1 לפני כל נתיב בטבלה זו.

קריאת יתרת הנקודות

GET /api/v1/verify/credits

במארח TrekMail הרגיל, התגובה כוללת את מכסת התוכנית ואת היתרה שנרכשה:

{
  "monthly_limit": 300,
  "monthly_used": 120,
  "monthly_remaining": 180,
  "purchased_balance": 5000,
  "total_available": 5180,
  "plan": "pro",
  "trialing": false,
  "resets_at": "2026-10-01T00:00:00+00:00"
}

במארח White Label, רק נקודות שנרכשו זמינות למוצר הממותג, ולכן התגובה מכילה את purchased_balance ואת total_available.

בקשה לדוגמה:

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/credits \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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

שדות יתרה

תגובות יתרה של White Label מכילות בכוונה פחות שדות, מפני שהמוצר הממותג משתמש רק בנקודות שנרכשו.

אימות כתובת אחת

POST /api/v1/verify

{
  "email": "person@example.com",
  "mode": "quick"
}

התגובה כוללת את email,‏ status,‏ trust_score,‏ checks,‏ provider,‏ risk_factors ו-credits_remaining. במארח הרגיל, credits_remaining מכיל את הערכים monthly ו-purchased. המבנה המפורט של checks עשוי להשתנות לפי המצב ולפי המידע שהספק המקבל מאפשר לקבל.

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

בקשה לדוגמה:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

יש להשתמש ב-status,‏ trust_score,‏ provider ו-risk_factors שברמה העליונה כחוזה הרגיל של היישום. checks מכיל ראיות תומכות שימושיות, אך המפתחות הנפרדים עשויים להשתנות כאשר בדיקה קודמת מדולגת או אינה זמינה, או כאשר Deep מקבל מידע נוסף.

פירוש תוצאה יחידה

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

יצירת משימה בכמות גדולה

POST /api/v1/verify/bulk

{
  "emails": ["first@example.com", "second@example.net"],
  "name": "September contacts",
  "mode": "deep"
}

רשומות כפולות עוברות נרמול לפני התמחור. משימה חדשה שנוצרה בהצלחה מחזירה 201 עם:

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

probe ו-skip מסבירים את חישוב המחיר של Deep. הערך deep_savings הוא ההפרש לעומת חיוב של כל כתובת שנשלחה בתעריף Deep המלא. רשימה כפולה מחזירה את job_id ואת הסטטוס הקיימים במקום להתחיל משימה נוספת.

בקשה לדוגמה:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -d '{"name":"September contacts","mode":"deep","emails":["first@example.com","second@example.net"]}'

ה-API בודק את הערכים שנשלחו לתחביר דוא"ל תקין לפני קבלת המשימה. אם כל הרשומות נדחות, הוא מחזיר 422 ואינו יוצר משימה. אם חלקן נדחות, התגובה המוצלחת מדווחת על rejected_count ועד חמישה ערכים ב-rejected_sample. אין להסתמך על מדגם קטן זה כדוח מלא לניקוי נתונים; יש לשמור את תוצאת אימות המקור במייבא שלכם.

רשימת בדיקה לשליחה בכמות גדולה

1. יש לקרוא ולנרמל את המקור ביישום שלכם.
2. יש להגביל את הבקשה ל-50,000 רשומות שנשלחו.
3. יש ליצור ולשמור מפתח אידמפוטנטיות לפני הבקשה.
4. יש לבחור שם משימה ברור מספיק כדי שמפעיל יזהה אותה בהמשך.
5. יש לשמור את job_id,‏ credits_charged ופירוט המחיר ש-TrekMail מחזיר.
6. יש לבצע polling ל-job_id שנשמר; אין להסיק שהמשימה הושלמה מבקשת HTTP המקורית.

קריאת משימה

GET /api/v1/verify/bulk/{jobId}

התגובה הבסיסית כוללת את job_id,‏ name,‏ status,‏ total,‏ processed,‏ progress,‏ summary,‏ created_at ו-completed_at.

כאשר יש תוצאות זמינות למשימה שהושלמה, הושלמה חלקית או נכשלה, התגובה כוללת גם:

{
  "results": [
    {
      "email": "person@example.com",
      "status": "valid",
      "trust_score": 82,
      "checks": {},
      "provider": "example.com",
      "risk_factors": ["no_dmarc"]
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "last_page": 1}
}

פרמטרים אופציונליים לשאילתה:

אפשר להוריד משימה שבוטלה אם יש בה שורות שעובדו, אך יש להשתמש בנקודת הקצה להורדה עבור הייצוא שלה.

קריאת מצבי משימה ללא ניחוש

לקוח API צריך לבצע polling עם השהיה הולכת וגדלה. אין לבצע שליחה חדשה בכמות גדולה רק מפני שהמשימה הקיימת עדיין ממתינה או מפני שבקשת רשת הגיעה ל-timeout מקומי.

דוגמה לתגובת סטטוס

{
  "job_id": 42,
  "name": "September contacts",
  "status": "processing",
  "total": 1500,
  "processed": 400,
  "progress": 27,
  "summary": {"safe": 220, "valid": 105, "risky": 55, "invalid": 20},
  "created_at": "2026-09-04T13:15:00+00:00",
  "completed_at": null
}

הערך summary יכול לגדול עם התקדמות העבודה. יש להשתמש ב-processed וב-total להצגת התקדמות במקום לסכם רק את הקטגוריות שהיישום מזהה כרגע.

הורדת משימה

GET /api/v1/verify/bulk/{jobId}/download

ההורדה זמינה למשימות שהושלמו, הושלמו חלקית או בוטלו ויש בהן שורות שעובדו. היא מזרימה CSV עם העמודות Email,‏ Status,‏ Trust Score,‏ Provider ו-Risk Factors.

דוגמה:

curl -o september-results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe_risky" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

יש לשמור את הפלט שהורד בתוך תקופת שמירת התוצאות של 15 ימים. ה-CSV הוא ייצוא לתהליך שלכם; הוא אינו משנה הסכמה, הרשמות או רשומות אנשי קשר במערכת אחרת.

נקודת הקצה להורדה מחזירה התנגשות כאשר אין ייצוא מעובד זמין. יש לבדוק תחילה את מצב המשימה. בקשה מוצלחת מזרימה את ה-CSV במקום להחזיר מעטפת JSON, לכן יש לטפל בה כתגובת קובץ בלקוח HTTP.

הצגת רשימת המשימות

GET /api/v1/verify/bulk

יש להשתמש ב-page,‏ per_page וב-status האופציונלי. ברירת המחדל של per_page היא 20 והוא מקבל ערכים מ-1 עד 100. הסטטוסים הם pending,‏ processing,‏ completed,‏ partial,‏ cancelled ו-failed.

התגובה מכילה מערך jobs ואובייקט pagination. בכל רשומת משימה יש ID, שם, סטטוס, סך הכול, מספר שעובד, התקדמות וחותמות זמן.

דוגמה:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk?status=processing&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

יש להשתמש בנקודת הקצה לרשימה כאשר worker מופעל מחדש או כאשר צריך להתאים מזהי משימות. אין להתייחס לשם משימה כמזהה ייחודי; יש לשמור את job_id המספרי שהוחזר.

מבנה תגובת רשימת המשימות

{
  "jobs": [
    {
      "job_id": 42,
      "name": "September contacts",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-09-04T13:15:00+00:00",
      "completed_at": "2026-09-04T13:28:00+00:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 20, "total": 1, "last_page": 1}
}

יש להשתמש בפרמטר השאילתה status כאשר דף תפעול צריך רק עבודה פעילה או רק עבודה שהסתיימה. עימוד חשוב לחשבונות שמאמתים רשימות רבות; אין להניח שתגובה אחת מכילה את כל ההיסטוריה.

ביטול משימה

POST /api/v1/verify/bulk/{jobId}/cancel

יש לבטל רק עבודה ממתינה או פעילה. תגובה מוצלחת היא:

{"status":"cancelled","credits_refunded":40}

ההחזר מיועד לעבודה שלא עובדה. אם המשימה הגיעה למצב סופי לפני שהביטול הגיע אליה, ה-API מחזיר התנגשות במקום לשנות את התוצאה.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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

מחיקת משימה

DELETE /api/v1/verify/bulk/{jobId}

יש לבטל תחילה משימה פעילה. המחיקה מסירה לצמיתות את המשימה ואת תוצאותיה לאחר ש-TrekMail מסיר באופן מאובטח את רשימת המקור שהוכנה. תגובה מוצלחת היא:

{"deleted":true}

curl -X DELETE https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 843ef0c5-4dc0-4c09-bacd-5bd0fe87e847"

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

סדר המחיקה

1. יש לקרוא את מצב המשימה.
2. יש לבטל אותה אם היא ממתינה או נמצאת בעיבוד.
3. יש לשמור כל ייצוא מעובד שחייבים לשמור.
4. יש למחוק את משימת האימות שאינה פעילה בעזרת מפתח אידמפוטנטיות.
5. יש להסיר עותקים שהמערכת מחזיקה לפי כללי הפרטיות והשמירה שלה.

שגיאות וניסיונות חוזרים

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

דפוס בטוח לניסיון חוזר

1. יש ליצור ולשמור מפתח אידמפוטנטיות אחד לפני שליחה בכמות גדולה.
2. יש לשלוח את הבקשה עם המפתח.
3. אם התגובה אובדת, יש לחזור על הבקשה הזהה עם אותו מפתח.
4. יש לשמור את job_id שהוחזר ולהפסיק ליצור שליחות חדשות עבור אותה רשימת מקור.
5. יש לבצע polling למשימה עד שתגיע למצב סופי, ואז להוריד או לעבד את התוצאה.

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

הגנה על נתוני אנשי קשר

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

TrekMail שומר תוצאות למשך 15 ימים. יש לתכנן אחסון מאובטח לייצוא או מסלול מחיקה לפני שילוב רשימות בנפח גבוה.

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