תיעוד למפתחים

שליחת אימייל דרך SMTP

הפנו כל אפליקציית SMTP ל-Banger, מ-Supabase Auth דרך WordPress ועד רכיב הדואר של מסגרת הפיתוח שלכם. מפתח Banger API הוא הסיסמה, וכל הודעה נמסרת מהדומיין שלכם ומופיעה ביומנים.

הגדרות

מארח	`submit.bangermail.com`
פורט	`465` עם TLS מההתחלה, או `587` עם STARTTLS. אם הרשת חוסמת אותם, השתמשו ב-`2465` (TLS) או `2587` (STARTTLS); פורט `25` מקבל גם STARTTLS.
שם משתמש	`banger`. כל ערך עובד: מפתח ה-API לבדו מזהה את סביבת העבודה.
סיסמה	מפתח Banger API עם הרשאת `mail:send`.
הצפנה	TLS 1.2 או חדש יותר. כניסה זמינה רק לאחר תחילת TLS, כך שמפתח לעולם אינו עובר ברשת כטקסט גלוי.
אימות	`PLAIN` או `LOGIN`.

לפני שמתחילים

צרו מפתח API. ב-אפליקציית Banger, פתחו את הגדרות → מפתחים → ניהול מפתחות API, בחרו יצירת מפתח API, בחרו mail:send והעתיקו את המפתח: הוא מוצג פעם אחת. העמוד מציג הגדרות SMTP אלה לצד המפתחות.
שלחו מנתיב מוצר. כתובת From חייבת להיות בשם מארח עם נתיב מוצר פעיל, הנתיב לקבלות, התראות ואימייל אחר מהאפליקציה. ב-דומיינים, בחרו הוספת נתיב, ואז מוצר, והוסיפו את רשומות ה-DNS המופיעות. נתיב דואר (תיבות הצוות) או נתיב קמפיין אינם מעבירים אימייל אפליקציה, כך שהדואר מהאפליקציה אינו יכול להשפיע על מוניטין תיבת הדואר הנכנס של הצוות.

דוגמה: Supabase Auth

בפרויקט Supabase שלכם, פתחו אימות → אימיילים → הגדרות SMTP והפעילו SMTP מותאם:

אימייל שולח	כתובת בנתיב המוצר שלכם, כגון `noreply@app.example.com`
שם שולח	שם המוצר שלכם. Banger מוסר אותו כפי שנכתב.
מארח	`submit.bangermail.com`
פורט	`465`
שם משתמש	`banger`
סיסמה	מפתח ה-API שלכם

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

דוגמה: Node.js

import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "submit.bangermail.com",
  port: 465,
  secure: true,
  auth: { user: "banger", pass: process.env.BANGER_API_KEY },
});

await transport.sendMail({
  from: "Acme <noreply@app.example.com>",
  to: "person@example.com",
  subject: "Your receipt",
  html: "<p>Thanks for your order.</p>",
});

לבדיקה ממסוף עם swaks:

swaks --server submit.bangermail.com:465 --tls-on-connect \
  --auth PLAIN --auth-user banger --auth-password "$BANGER_API_KEY" \
  --from noreply@app.example.com --to you@example.com

מה קורה לכל הודעה

Banger מוסר את ההודעה כפי שהאפליקציה כתבה, עם שם From שלכם, חתומה במפתח DKIM של הדומיין ונשלחת מדומיין ההחזרות של נתיב המוצר.
הוא מסיר Bcc, Return-Path וכותרות של Banger עצמו, ומוסיף Reply-To המציין את כתובת From כשאין כזה.
כל נמען נבדק ב-RCPT TO: כתובת חסומה נדחית בנפרד והשאר נשלחים.
הודעה יכולה להגיע ל-10 MiB עם עד 50 נמענים.
כותרת Idempotency-Key הופכת ניסיון חוזר לאותה שליחה. בלעדיה, ניסיון חוזר של אותה הודעה ונמענים עדיין מזוהה.
כל הודעה מופיעה ב-יומנים עם SMTP כמקור ונספרת בתוכנית כמו כל שליחה אחרת.

תשובות ושגיאות

דחייה מציינת את סיבתה וכוללת הפניה, (ref …), התואמת לרשומה ביומנים. קודים שמתחילים ב-4 זמניים: האפליקציה יכולה לנסות שוב מאוחר יותר.

תשובה	משמעות
`535 5.7.8`	הסיסמה אינה מפתח Banger API תקף, המפתח בוטל או שחסרה בו `mail:send`.
`421 4.7.0`	שלוש כניסות כושלות בחיבור אחד: הוא נסגר. בדקו את המפתח לפני ניסיון חוזר.
`454 4.7.0`	יותר מדי כניסות כושלות מהרשת שלכם בשעה האחרונה. נסו שוב מאוחר יותר.
`550 5.7.1`	לשם המארח של From אין נתיב מוצר מוכן לשליחה (התשובה מציינת מה חסר), נמען חסום או שהשליחה מושהית בגלל מוניטין.
`553 5.1.3`	כתובת נמען אינה תקפה.
`552 5.3.4`	ההודעה גדולה מ-10 MiB.
`554 5.6.0`	ההודעה אינה תקינה, למשל כותרת From או Subject חוזרת, או From עם יותר מכתובת אחת.
`451 4.7.0`	מכסת השליחה או המגבלה היומית של סביבת העבודה נוצלו. הן מתחדשות בתקופת החיוב או ביום הבאים, או עכשיו בשדרוג תוכנית.
`451 4.3.0`	Banger לא יכול היה לקבל את ההודעה כרגע. נסו שוב.

אבטחה

Banger שומר רק גיבוב של כל מפתח. בטלו או החליפו מפתח ב-ניהול מפתחות API; לקוחות SMTP שמשתמשים בו נדחים בכניסה הבאה.
תנו ל-SMTP מפתח משלו עם mail:send בלבד, כך שסיסמה שדלפה לא תוכל לקרוא את סביבת העבודה.
כניסות כושלות מוגבלות לכל רשת לקוח ולכל מפתח, וכניסה שנדחתה עם אחד המפתחות שלכם נרשמת ביומנים.

מעדיפים HTTP? אותה שליחה זמינה דרך Banger API.