Mailbox Docs
Dashboard
QuickstartAuthenticationელფოსტის გაგზავნაDefault და custom შაბლონებიRate limitsErrorsსაუკეთესო პრაქტიკები
API Reference

Mailbox API დოკუმენტაცია

გააგზავნე საკონტაქტო ფორმისა და პროდუქტის წერილები დამტკიცებული დომენის alias-ებიდან მარტივი server-side API-ით.

Base URL

https://your-domain.com

Authentication

Bearer mk_live_xxxxx
დაწყება

Quickstart

შექმენი alias, მისთვის დაამატე API key და send endpoint გამოიძახე შენი server-იდან. Browser JavaScript-იდან გამოძახება არ შეიძლება.

  • API key გამოიყენე მხოლოდ backend-ზე.
  • თითოეული key წერილს მხოლოდ არჩეული alias-ებიდან აგზავნის.
  • თუ custom შაბლონს არ მიუთითებ, default შაბლონი data-ს ავტომატურად დაალაგებს.
const response = await fetch("https://your-domain.com/api/v1/email/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer mk_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    from: "[email protected]",
    to: "[email protected]",
    subject: "New website message",
    replyTo: "[email protected]",
    data: {
      name: "Nino",
      email: "[email protected]",
      message: "Hello from the contact form"
    }
  })
});

const result = await response.json();
უსაფრთხოება

Authentication

ყველა request იყენებს bearer authentication-ს. key შეინახე environment variables-ში ან secrets vault-ში. სრული key მხოლოდ შექმნის მომენტში გამოჩნდება.

Authorization: Bearer mk_live_xxxxx
Endpoint

ელფოსტის გაგზავნა

POST/api/v1/email/send

გამოიყენე POST /api/v1/email/send დამტკიცებული alias-იდან წერილის გასაგზავნად. მიღების შემდეგ endpoint აბრუნებს გაგზავნილი წერილის id-ს.

from
emailrequired
დამტკიცებული alias მისამართი, რომელზეც API key-ს უფლება აქვს.
to
stringrequired
მიმღების ელფოსტა ან მძიმით გამოყოფილი მიმღებების სია.
subject
stringoptional
წერილის სათაური. საჭირო არ არის, თუ შაბლონს subject აქვს.
replyTo
emailoptional
საკონტაქტო ფორმის სტუმრის ელფოსტა, რომ პასუხი მასთან მივიდეს.
data
objectoptional
ველები default შაბლონისთვის ან custom შაბლონის ცვლადებისთვის.
template
stringoptional
არასავალდებულო შაბლონის slug, მაგალითად contact-form.
html
stringoptional
არასავალდებულო raw HTML body. თუ text/template-იც არ არის, default შაბლონი გამოიყენება.
text
stringoptional
არასავალდებულო plain text body.
Templates

Default და custom შაბლონები

თუ template, html და text არ მოვა, Mailbox data-დან სუფთა default წერილს ააწყობს. custom layout-ისთვის შექმენი შაბლონი slug-ით და გამოიყენე placeholder-ები: {{name}}, {{email}}, {{message}}.

await fetch("https://your-domain.com/api/v1/email/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MAILBOX_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    from: "[email protected]",
    to: "[email protected]",
    template: "contact-form",
    data: {
      name: "Nino",
      email: "[email protected]",
      message: "I want to discuss a project"
    }
  })
});
Limits

Rate limits

თითოეული API key შეზღუდულია წუთში request-ების რაოდენობით, რომ delivery ყველა Mailbox მომხმარებლისთვის სტაბილური დარჩეს. ლიმიტის გადაჭარბებისას API აბრუნებს 429 Too Many Requests-ს და Retry-After header-ს, სადაც მითითებულია, რამდენი წამის შემდეგ უნდა სცადო თავიდან.

Standard keys
60 req/minoptional
ნაგულისხმევი ლიმიტი ნებისმიერი გეგმის API key-სთვის.
Retry-After
headeroptional
წამები, რომლის შემდეგაც შემდეგი request წარმატებული იქნება.
HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "error": "rate_limited", "message": "Too many requests, retry later." }
Reference

Errors

API იყენებს სტანდარტულ HTTP status codes-ს და JSON error responses-ს.

400
Bad Requestoptional
არასწორი request body ან აკლია შაბლონის ცვლადები.
401
Unauthorizedoptional
API key აკლია, არასწორია ან გაუქმებულია.
403
Forbiddenoptional
key-ს ამ alias-იდან გაგზავნის უფლება არ აქვს.
404
Not Foundoptional
შაბლონი ან resource ვერ მოიძებნა.
429
Too Many Requestsoptional
Rate limit გადაცილებულია. შეამოწმე Retry-After header.
Guide

საუკეთესო პრაქტიკები

რამდენიმე რჩევა, რომელიც production ინტეგრაციას უფრო საიმედოს ხდის.

  • test და live API key-ები შეინახე ცალკე environment variables-ში და არასდროს ჩაწერო source code-ში.
  • 429 პასუხზე გამოიყენე exponential backoff, ნაცვლად დაუყოვნებლივი retry-ისა.
  • API-ს გამოძახებამდე შეამოწმე, რომ from მისამართი შენი key-ის დაშვებულ alias-ს ემთხვევა. ასე შეცდომას უფრო სწრაფად დაიჭერ.
  • შეინახე დაბრუნებული message id, რომ გაგზავნა dashboard-ის delivery სტატუსს დაუკავშირო.