התחלה מהירה עם API של Email Verifier

השתמשו ב-API כאשר האימות צריך להיות חלק מהמוצר או מתהליך הייבוא שלכם. צרו אסימון עם ההיקפים verify:read ו-verify:write, שמרו עליו בסוד ופנו לאותו מארח שבו אתם משתמשים כדי להיכנס. בדוגמאות, החליפו את https://YOUR-TREKMAIL-HOST ואת YOUR_API_TOKEN.

1. יצירת אסימון

1. פתחו את לוח הבקרה ← AI Agents & API.
2. צרו אסימון.
3. הפעילו את verify:read ואת verify:write.
4. אחסנו את האסימון בבטחה. הוא מוצג פעם אחת בלבד.

שלחו אותו בכל בקשה:

Authorization: Bearer YOUR_API_TOKEN

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

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

השתמשו ב-POST /api/v1/verify לקבלת תוצאה מיידית עבור כתובת אחת. Quick הוא ברירת המחדל כאשר mode מושמט.

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"}'

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

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

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

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

3. שליחת משימה מרוכזת

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

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

הרשימה יכולה להכיל עד 50,000 רשומות. TrekMail מנרמל כפילויות ודוחה מהמשימה רשומות שאינן תקינות מבחינה תחבירית. התגובה מדווחת על מזהה המשימה, הכמות שהתקבלה, מדגם קטן של רשומות שנדחו, נקודות הזכות שחויבו ופירוט תמחור Deep.

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

probe הוא המספר שחויב בתעריף Deep המלא. skip הוא המספר שחויב בתעריף הרגיל מכיוון שהספק אינו מספק ראיות שימושיות ברמת תיבת הדואר. התגובה מספקת את העלות הקובעת עבור השליחה הזאת.

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

4. בדיקת מצב והורדה

בדקו את המשימה באמצעות GET /api/v1/verify/bulk/{jobId} עד שתגיע למצב סופי:

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

התגובה כוללת את status, total, processed, progress, summary, זמן היצירה וזמן ההשלמה. משימות שהושלמו או הושלמו חלקית כוללות מערך results המחולק לעמודים.

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

לאחר שהתוצאות זמינות, אפשר לבקש עמוד תוצאות קטן יותר או לחפש כתובת מוכרת:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

הורידו משימה שעובדה כ-CSV:

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

מסנני הייצוא של API הם all, safe ו-safe_risky (Safe + Valid + Risky).

כדי לעצור משימה ממתינה או פועלת, השתמשו ב-endpoint הביטול. הוא מחזיר נקודות זכות על עבודה שלא עובדה ושומר שורות שכבר עובדו:

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

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

5. טיפול בתגובות נפוצות

• 402: החשבון זקוק לנקודות זכות נוספות.
• 422: בדקו את גוף הבקשה, את המצב שנבחר או מפתח אידמפוטנטיות שנדרש לבקשה מרוכזת.
• 429: האטו ונסו שוב תוך הגדלה הדרגתית של זמן ההמתנה.
• 503: האימות אינו זמין באופן זמני. נסו שוב מאוחר יותר; נקודות הזכות עבור אימות כתובת יחיד שנכשל מוחזרות.

רשימת תיוג לשילוב בסביבת ייצור

1. שמרו את האסימון בצד השרת והעניקו רק את שני היקפי Verifier הנדרשים.
2. אמתו ונרמלו קלט של אנשי קשר לפני הקריאה ל-API המרוכז.
3. שמרו את מזהה המשימה, מזהה הרשימה שנשלחה, מפתח האידמפוטנטיות ואת ערך credits_charged שהוחזר.
4. בדקו תוך הגדלת זמן ההמתנה במקום להשתמש בלולאה צפופה.
5. שמרו או עבדו את קובץ CSV לפני סיום תקופת השמירה של 15 יום.
6. שמרו את החלטות ההסכמה, ההסרה מרשימת התפוצה וההחרגה ביישום שלכם. תוצאת Verifier אינה מחליפה אותן.

לכל ה-endpoints, ההיקפים ושדות התגובה, השתמשו במדריך REST API של Email Verifier.