יצירה וניהול של מפתח ה-API שלכם

Published: 16 ביולי 2026 · Last updated: 21 ביולי 2026 · By Marcus Biel

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

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

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

למה משמש מפתח ה-API

השתמשו במפתח ה-API כאשר תוכנה מחוץ ל-Maildroppa צריכה לעבוד עם Maildroppa ללא התחברות אינטראקטיבית של משתמש.

דוגמאות נפוצות כוללות:

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

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

הדף מסומן כעת כ-“beta”. השתמשו בתיעוד OpenAPI המקושר כמקור לנקודות הקצה, לגופי הבקשות, לפרמטרים ולסכמות התגובה הנתמכים כעת על ידי ה-API.

פתיחת דף מפתח ה-API

פתחו את “Settings”, הרחיבו את “Developers” ובחרו “API key”.

ניתן גם לפתוח את הדף ישירות בכתובת:

https://app.maildroppa.com/settings/developers/api-key

הדף כולל:

• חלונית של מפתח API עם תג beta.
• קישור “View OpenAPI docs”.
• מצב ריק וכפתור “Create API key” כאשר לא קיים מפתח.
• ייצוג מוסתר של המפתח הנוכחי כאשר קיים מפתח.
• כפתור “Copy” שמעתיק את המפתח המלא.
• פעולות “Rotate API key” ו-“Delete API key” להחלפה או להסרה של המפתח הנוכחי.

Maildroppa מאפשרת מפתח API אחד לכל חשבון. הדף אינו יוצר מפתחות נפרדים עבור יישומים, סביבות או חברי צוות בודדים.

יצירת מפתח API

כאשר בדף מופיע “No API key yet”, לחצו על “Create API key”.

Maildroppa יוצרת את המפתח מיד. ביצירה הראשונה אין תיבת דו-שיח לאישור. בזמן שהבקשה מתבצעת, הכפתור משתנה ל-“Creating API key” והדף משבית זמנית פעולות נוספות הקשורות למפתח.

לאחר יצירת המפתח:

• המצב הריק נעלם.
• מופיע מפתח מוסתר.
• פעולות “Copy”, “Rotate API key” ו-“Delete API key” הופכות לזמינות.
• Maildroppa מציגה הודעת הצלחה “API key updated”.

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

הבנת המפתח המוסתר

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

a1b2c*****

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

לחצו על “Copy” כדי לכתוב את המפתח המלא הנוכחי ללוח. לאחר העתקה מוצלחת, הכפתור משתנה לזמן קצר ל-“Copied!”.

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

אחסון המפתח בצורה בטוחה

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

מיקומים מתאימים כוללים:

• מנהל סודות מנוהל.
• תצורת סביבה מוגנת בשרת.
• סוד פריסה מוצפן.
• מנהל סיסמאות המשמש לשחזור תפעולי.

אין לאחסן את המפתח ב:

• JavaScript בצד הדפדפן או בחבילת frontend אחרת הניתנת להורדה.
• קובץ קוד מקור ציבורי או פרטי שנשמר במאגר.
• כתובת URL או פרמטר שאילתה.
• תיעוד ציבורי, צילומי מסך, הודעות תמיכה או מערכות לניהול תקלות.
• יומני יישום משותפים, אירועי אנליטיקה או דוחות שגיאה.
• גיליון אלקטרוני לא מוצפן או צ'אט צוות רגיל.

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

שימוש במפתח ה-API

שלחו את המפתח המלא בכותרת בקשת HTTP בשם X-API-Key:

X-API-Key: your-complete-api-key

אין לשלוח אותו כאסימון Bearer. Maildroppa מצפה ל-X-API-Key, ולא ל-Authorization: Bearer ....

ה-API בסביבת הייצור והתיעוד האינטראקטיבי של OpenAPI זמינים בכתובת:

https://api.maildroppa.com

לחצו על “View OpenAPI docs” בדף מפתח ה-API כדי לפתוח את התיעוד בכרטיסיית דפדפן חדשה. בחרו שם נקודת קצה כדי לעיין בשיטה, בנתיב, בפרמטרים, בגוף הבקשה, בסוג התגובה ובקודי הסטטוס האפשריים שלה.

דוגמת בקשה

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

curl --request GET \
  --url 'https://api.maildroppa.com/subscribers?pageNumber=1' \
  --header 'Accept: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}"

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

בקשות עם גופי JSON

עבור בקשה ששולחת JSON, כללו גם:

Content-Type: application/json

לדוגמה, המבנה הבסיסי הוא:

curl --request POST \
  --url 'https://api.maildroppa.com/example-endpoint' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}" \
  --data '{"example":"value"}'

/example-endpoint והגוף שלו הם מצייני מקום. החליפו אותם בנקודת קצה מתועדת ובסכמת הבקשה המתועדת שלה.

למה המפתח יכול לגשת

המפתח פועל רק עם נקודות קצה התומכות באימות באמצעות מפתח API. דף או בקשה המשמשים באופן פנימי את יישום Maildroppa אינם נכללים אוטומטית ב-API הציבורי ללקוחות.

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

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

מגבלות קצב

החוזה הנוכחי של OpenAPI מתעד את המגבלות הבאות למפתחות API:

• ברירת המחדל של API הלקוחות: 300 בקשות בדקה ו-2,000 בקשות בשעה.
• Events API ב-/events: 100 בקשות בשנייה עם קיבולת burst של 500 בקשות.

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

כאשר Maildroppa מחזירה 429 Too Many Requests, הפסיקו לשלוח בקשות חדשות וכבדו את כותרת התגובה Retry-After כאשר היא קיימת. השתמשו בתור ובהשהיה הדרגתית מבוקרת במקום להפעיל ניסיונות חוזרים מקבילים רבים.

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

שימוש במפתח עבור בקשות API של Automation

Automation יכול להתחיל כאשר המערכת שלכם שולחת אירוע מותאם אישית ל-Events API של Maildroppa.

כאשר מגדירים טריגר מסוג “API request”, Maildroppa משתמשת באותו מפתח API של החשבון המנוהל בדף זה. הגדרת הטריגר יכולה ליצור את המפתח כאשר לא קיים מפתח, ולהעתיק בקשת curl מוכנה המכילה את המפתח המלא.

יש לכך שתי השלכות חשובות:

• החלפה או מחיקה של מפתח החשבון משפיעה גם על מערכות ששולחות אירועים מותאמים אישית ל-Automations.
• דוגמת בקשת Automation שהועתקה מכילה את הסוד בלוח, אף שהמפתח מוסתר על המסך.

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

איפוס או החלפת מפתח ה-API

השתמשו ב-“Rotate API key” כאשר עליכם לאפס או להחליף את פרטי הגישה הנוכחיים. Maildroppa יוצרת מפתח חדש ומבטלת את המפתח הקודם כחלק מאותה פעולה.

השתמשו בהחלפה כאשר:

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

לחצו על “Rotate API key” מתחת למפתח המוסתר. Maildroppa פותחת תיבת אזהרה המסבירה שהמפתח הקיים לא יהיה עוד שמיש.

לחצו על “Rotate API key” בתיבת הדו-שיח כדי להמשיך, או על “Cancel” כדי להשאיר את המפתח הנוכחי.

להחלפה אין תקופת חסד

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

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

השתמשו ברצף הבא להחלפה מתוכננת:

1. רשמו כל אינטגרציה שמשתמשת במפתח הנוכחי.
2. הכינו גישה לתצורת הסודות ולתהליך הפריסה של כל אינטגרציה.
3. בחרו חלון תחזוקה קצר אם גישה רציפה ל-API חשובה.
4. לחצו על “Rotate API key”, ולאחר מכן אשרו את האזהרה באמצעות “Rotate API key” בתיבת הדו-שיח.
5. לחצו על “Copy” כדי להעתיק את המפתח החדש המלא.
6. החליפו מיד את הסוד בכל אינטגרציה.
7. הפעילו מחדש או פרסו מחדש שירותים שטוענים סודות רק בעת ההפעלה.
8. שלחו בקשה מתועדת ולא מזיקה כדי לאמת כל אינטגרציה.
9. בדקו אם מתקבלות תגובות 401 Unauthorized משירות שנשכח ועדיין משתמש במפתח הישן.

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

מחיקת מפתח ה-API

מחקו את המפתח כאשר החשבון לא אמור עוד לקבל בקשות המאומתות באמצעות מפתח API.

לחצו על “Delete API key” מתחת למפתח המוסתר. Maildroppa פותחת תיבת אזהרה המסבירה שהמפתח יוסר לצמיתות מהחשבון.

לחצו על “Delete API key” בתיבת הדו-שיח כדי למחוק אותו, או על “Cancel” כדי להשאירו.

לאחר המחיקה:

• המפתח הנוכחי מפסיק לפעול מיד.
• הדף חוזר למצב “No API key yet”.
• אינטגרציות שרת המשתמשות במפתח שנמחק אינן יכולות עוד לבצע אימות.
• שולחי בקשות API של Automation המשתמשים במפתח זה אינם יכולים עוד למסור אירועים.

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

ניתן ללחוץ על “Create API key” מאוחר יותר כדי ליצור פרטי גישה חדשים. הערך שנמחק לא ישוחזר. יש לעדכן כל אינטגרציה לפני שתוכל להשתמש במפתח החדש.

איפוס או מחיקה: במה לבחור?

בחרו ב-“Rotate API key” כאשר הגישה ל-API צריכה להימשך באמצעות פרטי גישה חדשים.

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

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

המלצות אבטחה

השאירו את קריאות ה-API בשרת שלכם

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

אם אתר או אפליקציה צריכים להפעיל פעולה, שלחו תחילה את הבקשה ל-backend המאומת שלכם. תנו ל-backend לאמת את המשתמש ולקרוא ל-Maildroppa באמצעות המפתח המאוחסן בשרת.

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

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

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

הסירו כותרות בקשות מיומנים

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

שמרו על הפרדה בין סביבות

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

הקישור “View OpenAPI docs” מפנה אוטומטית משתמשי ייצור לתיעוד ה-API של הייצור. ודאו תמיד את שם המארח לפני שליחת מפתח אמיתי.

בצעו החלפה לאחר כל חשיפה חשודה

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

טיפול בשגיאות API

השתמשו בסטטוס ה-HTTP ובגוף התגובה המתועד כדי להחליט מה האינטגרציה צריכה לעשות.

מקרים נפוצים כוללים:

• 400 Bad Request — הנתיב, הפרמטר או גוף ה-JSON אינם עומדים בחוזה של נקודת הקצה. השוו את הבקשה לסכמת OpenAPI.
• 401 Unauthorized — כותרת X-API-Key חסרה, ריקה, לא תקפה, נמחקה או מכילה ערך ישן לאחר החלפה.
• 403 Forbidden — למפתח המאומת אין הרשאה להשתמש בפעולה זו.
• 404 Not Found — הנתיב או המשאב שאליו מפנים אינם קיימים בחשבון זה.
• 429 Too Many Requests — האינטגרציה הגיעה למגבלת קצב API. השהו בקשות וכבדו את כותרת Retry-After כאשר היא קיימת.
• 5xx — Maildroppa לא הצליחה להשלים את הבקשה. נסו שוב פעולות בטוחות עם השהיה מעריכית מוגבלת ועם רישום שאינו כולל את מפתח ה-API.

אל תנסו שוב כל כשל באופן עיוור. תקנו תגובות 400, 401, 403 ורוב תגובות 404 לפני שליחת אותה בקשה שוב.

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

פתרון בעיות

“Create API key” עדיין מופיע

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

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

המפתח בדף נראה קצר מדי

הדף מציג בכוונה רק את חמשת התווים הראשונים ואת *****. לחצו על “Copy” כדי להעתיק את הערך המלא. אל תשלחו את הטקסט המוסתר בבקשה.

“Copy” אינו משתנה ל-“Copied!”

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

אל תנסו לשחזר את המפתח מהטקסט המוסתר.

בקשה מחזירה 401 Unauthorized

בדקו ש:

• שם הכותרת הוא בדיוק X-API-Key.
• הכותרת מכילה את הערך המלא, ללא הכוכביות המוצגות.
• האינטגרציה אינה שולחת Authorization: Bearer במקום זאת.
• לא נוספו לסוד רווחים, מרכאות או ירידת שורה.
• איש לא החליף או מחק את מפתח החשבון.
• השירות הופעל מחדש אם הוא קורא משתני סביבה רק בעת ההפעלה.
• הבקשה נשלחת לסביבת Maildroppa API הנכונה.

אינטגרציה אחת פועלת אך אחרת הפסיקה לאחר החלפה

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

דף OpenAPI פועל אך נקודת קצה מחזירה 403

לא כל נקודת קצה של היישום תומכת באימות באמצעות מפתח API. השתמשו בפעולה המתועדת עבור ה-API ללקוחות ואשרו את דרישות האימות שלה בדף OpenAPI.

בקשות מחזירות 429 Too Many Requests

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

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

לפני העברת אינטגרציה לשימוש שוטף, ודאו ש:

• המפתח מאוחסן רק בתצורת סודות בצד השרת.
• הבקשות משתמשות בכותרת X-API-Key.
• האינטגרציה משתמשת ב-https://api.maildroppa.com בייצור.
• כל שיטה, נתיב, פרמטר וגוף JSON תואמים לתיעוד OpenAPI.
• היומנים ודוחות השגיאות מסירים את המפתח.
• מוגדרים timeouts וניסיונות חוזרים מוגבלים.
• מנוטרות שגיאות 401, 403, 429 ושגיאות שרת.
• בעל האינטגרציה מתועד.
• כל מערכת שחולקת את מפתח החשבון נכללת בתוכנית ההחלפה.
• ניתן להחליף במהירות מפתח שנפגע.

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