Send API és SMTP

Az SRVO Send az alább felsorolt végpontoknál a Resend helyére állítható. Az alap-URL https://api.srvo.app, a bearer token pedig egy Send-kulcs. A Resend-kompatibilis útvonalakhoz nem tartozik /api/v1 utótag.

Először ellenőrizze a domaint, és hozzon létre Send-kulcsot. A kulcsot az alkalmazás titkos beállításai között, SRVO_SEND_KEY néven tárolja. A Send-kulcs a kompatibilis API-val és SMTP-vel használható. Különbözik az általános SRVO API-kulcstól és az MCP-bejelentkezéstől.

A Resend SDK használata

Állítsa a Resend SDK baseUrl értékét az SRVO címére. Használjon az ellenőrzött domainhez tartozó feladót, és cserélje ki a példa címzettjét.

pnpm add resend

import { Resend } from "resend";

const resend = new Resend(process.env.SRVO_SEND_KEY, {
  baseUrl: "https://api.srvo.app",
});

const { data, error } = await resend.emails.send({
  from: "Example <hello@mail.example.com>",
  to: ["recipient@example.com"],
  subject: "Hello",
  html: "<p>Hello from SRVO Send.</p>",
});

if (error) throw new Error(error.message);
console.log(data?.id);

Küldés curl segítségével

A sikeres kérés válasza { "id": "…" }. Ez sorba állítást jelent, nem kézbesítést.

export SRVO_SEND_KEY='your-send-key'
curl --fail-with-body https://api.srvo.app/emails \
  -H "Authorization: Bearer $SRVO_SEND_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: welcome-order-123' \
  -d '{"from":"Example <hello@mail.example.com>","to":["recipient@example.com"],"subject":"Hello","html":"<p>Hello from SRVO Send.</p>"}'

Elérhető végpontok

Az /api-keys útvonalon csak a listázás érhető el. Kulcsot a Send → API-kulcsok oldalon hozhat létre és vonhat vissza, vagy a natív SRVO API-n keresztül, annak saját hitelesítésével. A kompatibilis API kezelési műveleteihez full_access Send-kulcsot használjon. A sending_access kulcs küldésre való, és a saját időzített üzenetek engedélyezett módosításaira is használható.

Biztonságos újrapróbálás

A POST /emails és POST /emails/batch kérésekhez adjon meg Idempotency-Key fejlécet. Értéke 1–256 karakter lehet. Az SRVO 24 órán át őrzi meg a kulcsot. Ugyanannak a küldésnek az újrapróbálásakor ugyanazt a kulcsot és tartalmat használja. Másik küldéshez új kulcsot adjon meg.

Ha ugyanahhoz a kulcshoz más tartalom tartozik, a válasz 409 invalid_idempotent_request. Párhuzamos kérésnél 409 concurrent_idempotent_requests érkezhet. Később próbálja újra ugyanazzal a kulccsal.

Mellékletek és üzenetkorlátok

A mellékletet base64 formában a content mezőben, vagy HTTPS URL-ként a path mezőben adhatja meg. A content értékében ne használjon data-URL előtagot.

{
  "attachments": [
    { "filename": "hello.txt", "content": "SGVsbG8=" },
    { "filename": "invoice.pdf", "path": "https://example.com/invoice.pdf" }
  ]
}

• Összesen legfeljebb 50 címzett adható meg a to, cc és bcc mezőkben.
• Legfeljebb 50 melléklet küldhető, ebből legfeljebb 10 URL-lel.
• Egy URL-ről letöltött melléklet legfeljebb 8 MiB lehet, nyilvános HTTPS címről. A letöltési időkorlát 10 másodperc. Belső hálózati címek nem használhatók.
• A teljes üzenet legfeljebb 40 MiB lehet, a base64 mellékletekkel együtt. A base64 kódolás körülbelül harmadával növeli a fájl méretét. A html és a text mező külön-külön legfeljebb 2 097 152 karakter lehet.
• Futtatható fájlok és tiltott szkriptfájlok nem küldhetők. A kötegelt küldés nem fogad mellékletet vagy időzítést.

Hibák és kérési korlátok

A hibaválasz a statusCode, name és message mezőket tartalmazza:

{ "statusCode": 401, "name": "missing_api_key", "message": "…" }

• 400: érvénytelen idempotenciakulcs.
• 401: hiányzó, érvénytelen vagy korlátozott Send-kulcs.
• 403: nem ellenőrzött domain, tiltott domain vagy hozzáférés, illetve szüneteltetett küldésnél security_error.
• 404: az erőforrás nem található.
• 409: ütközés vagy idempotenciahiba.
• 422: hibás kérési mezők.
• 429: rate_limit_exceeded, daily_quota_exceeded vagy monthly_quota_exceeded.
• 5xx: átmeneti szerverhiba. Növekvő várakozási idővel, ugyanazzal az idempotenciakulccsal próbálja újra.

A kompatibilis API jelenleg másodpercenként 10 kérést enged munkaterületenként, az útvonalak között megosztva. Figyelje a ratelimit-limit, ratelimit-remaining és ratelimit-reset fejléceket. Ha a 429-es válaszban van Retry-After, várja meg az ott jelzett időt. Kvótahibánál meg kell várni, amíg felszabadul a küldési vagy indulási keret. Az azonnali újrapróbálás nem segít. Lásd a küldési korlátokat és a fokozatos indulást.

SMTP-átjátszó

Az SMTP-kliensben ezeket állítsa be:

• Kiszolgáló: smtp.srvo.app.
• Port: 56747.
• Biztonság: implicit TLS, gyakran SSL/TLS néven; Nodemailer esetén secure: true.
• Felhasználónév: resend vagy srvo.
• Jelszó: az Ön Send-kulcsa.

A feladónak a kulcs számára engedélyezett, ellenőrzött domainhez kell tartoznia. A nyers üzenet legfeljebb 28 MiB, azaz körülbelül 28 MB lehet, a MIME-fejlécekkel és kódolt mellékletekkel együtt. Összesen legfeljebb 50 címzett lehet. A fenti portot használja, ne automatikusan a 465-öt vagy az 587-et.

Payload CMS

Payload CMS v3 esetén használja az @srvosystems/payload-email csomagot. A csomag a GitHub Packages rendszerében érhető el. Adja az alábbiakat a projekt .npmrc fájljához. A GITHUB_TOKEN értékét környezeti változóként adja meg, read:packages jogosultsággal és a csomaghoz való hozzáféréssel. A tokent ne mentse a verziókövetésbe.

@srvosystems:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

pnpm add @srvosystems/payload-email

// payload.config.ts
import { buildConfig } from "payload";
import { srvoSendAdapter } from "@srvosystems/payload-email";

export default buildConfig({
  email: srvoSendAdapter({
    apiKey: process.env.SRVO_SEND_KEY!,
    defaultFromAddress: "hello@mail.example.com",
    defaultFromName: "Example",
  }),
  // Itt adja meg a gyűjteményeket és a többi Payload-beállítást.
});

Cserélje a feladót az ellenőrzött domainhez tartozó címre. Az adapter alapértelmezett címe https://api.srvo.app. A payload.sendEmail(...) a megszokott módon használható. A visszaadott id azonosítja az üzenetet a Send modulban.

Hamarosan érkezik

A körlevelek, a közönség és névjegyek kezelése, a sablonok és a Domain Connect automatikus DNS-beállítása hamarosan érkeznek. Ez az útmutató a már elérhető tranzakciós küldési útvonalakat mutatja be.