Wysyłaj e-maile przez REST lub SMTP.

Uwierzytelnianie

Obie metody używają tych samych poświadczeń: klucza API, który ma key ID (publiczny) i key secret. Klucze utworzysz w panelu na app.onesend.eu.

Uwierzytelnianie REST używa tokenu Bearer złożonego z key ID i key secret połączonych dwukropkiem:

Authorization: Bearer YOUR_KEY_ID:YOUR_KEY_SECRET

W SMTP key ID jest nazwą użytkownika, a key secret hasłem. Nie ma osobnych poświadczeń SMTP do wygenerowania. Klucz API jest poświadczeniem zarówno dla REST, jak i SMTP.

Zweryfikuj domenę wysyłki

Możesz wysyłać tylko z adresu w domenie, którą dodałeś i zweryfikowałeś. Jest to wymagane również w okresie próbnym, aby chronić reputację współdzielonego IP. Weryfikację wykonujesz raz, w panelu.

Gdy dodajesz domenę, onesend generuje klucz DKIM i podaje cztery rekordy TXT do opublikowania u Twojego dostawcy DNS:

To DKIM decyduje o weryfikacji. SPF i DMARC są zdecydowanie zalecane, ale domena jest weryfikowana wyłącznie na podstawie DKIM. Selektor DKIM to onesend. Jeśli masz już rekord SPF, dodaj include:onesend.eu do istniejącego rekordu, zamiast tworzyć drugi, ponieważ domena może mieć tylko jeden rekord SPF. Zmiany DNS propagują się od kilku minut do kilku godzin.

Wysyłanie przez API REST

POST https://api.onesend.eu/v1/email/send
Authorization: Bearer YOUR_KEY_ID:YOUR_KEY_SECRET
Content-Type: application/json

Treść żądania:

{
  "from": "hello@yourdomain.com",
  "to": ["recipient@example.com"],
  "cc": ["optional@example.com"],
  "bcc": ["optional@example.com"],
  "reply_to": "reply@yourdomain.com",
  "subject": "Hello from onesend",
  "html": "<h1>It works</h1>",
  "text": "It works",
  "headers": { "X-Custom": "value" },
  "tags": { "campaign": "welcome" }
}

Pola wymagane to from, to, subject oraz co najmniej jedno z html lub text. Adres from musi być w zweryfikowanej domenie. Pola cc, bcc, reply_to, text, headers i tags są opcjonalne.

Po powodzeniu odpowiedź to 202 Accepted, a wiadomość trafia do kolejki do dostarczenia:

{ "message_id": "...", "status": "queued" }

Jeśli odbiorca jest na Twojej liście wykluczeń, żądanie nadal zwraca 200 (to nie błąd), wysyłka jest pomijana i nie jest naliczana:

{ "message_id": "...", "status": "suppressed", "reason": "Recipient on suppression list (bounce)" }

Wysyłanie przez SMTP

Skieruj istniejący mailer SMTP na onesend. Poza hostem i poświadczeniami nie ma zmian w kodzie.

Host:     smtp.onesend.eu
Port:     587
Security: STARTTLS (required)
Username: YOUR_KEY_ID
Password: YOUR_KEY_SECRET

Obowiązują te same zasady co w REST: adres From musi być w zweryfikowanej domenie, a odbiorcy wykluczeni są pomijani i nie są naliczani.

Przykłady kodu

curl (REST)

curl -X POST https://api.onesend.eu/v1/email/send \
  -H "Authorization: Bearer $ONESEND_KEY_ID:$ONESEND_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["recipient@example.com"],
    "subject": "Hello from onesend",
    "html": "<h1>It works</h1>",
    "text": "It works"
  }'

Node.js (REST, fetch)

const res = await fetch("https://api.onesend.eu/v1/email/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ONESEND_KEY_ID}:${process.env.ONESEND_KEY_SECRET}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "hello@yourdomain.com",
    to: ["recipient@example.com"],
    subject: "Hello from onesend",
    html: "<h1>It works</h1>",
  }),
});
const data = await res.json();
console.log(res.status, data);

Node.js (SMTP, nodemailer)

import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "smtp.onesend.eu",
  port: 587,
  requireTLS: true,
  auth: {
    user: process.env.ONESEND_KEY_ID,
    pass: process.env.ONESEND_KEY_SECRET,
  },
});

await transport.sendMail({
  from: "hello@yourdomain.com",
  to: "recipient@example.com",
  subject: "Hello from onesend",
  html: "<h1>It works</h1>",
});

Python (REST, requests)

import os, requests

r = requests.post(
    "https://api.onesend.eu/v1/email/send",
    headers={
        "Authorization": f"Bearer {os.environ['ONESEND_KEY_ID']}:{os.environ['ONESEND_KEY_SECRET']}"
    },
    json={
        "from": "hello@yourdomain.com",
        "to": ["recipient@example.com"],
        "subject": "Hello from onesend",
        "html": "<h1>It works</h1>",
    },
)
print(r.status_code, r.json())

Python (SMTP, smtplib)

import os, smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "hello@yourdomain.com"
msg["To"] = "recipient@example.com"
msg["Subject"] = "Hello from onesend"
msg.set_content("It works")
msg.add_alternative("<h1>It works</h1>", subtype="html")

with smtplib.SMTP("smtp.onesend.eu", 587) as s:
    s.starttls()
    s.login(os.environ["ONESEND_KEY_ID"], os.environ["ONESEND_KEY_SECRET"])
    s.send_message(msg)

PHP (REST, curl)

$ch = curl_init("https://api.onesend.eu/v1/email/send");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer {$keyId}:{$keySecret}",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "from" => "hello@yourdomain.com",
    "to" => ["recipient@example.com"],
    "subject" => "Hello from onesend",
    "html" => "<h1>It works</h1>",
  ]),
]);
$response = curl_exec($ch);

Każdy inny język, framework lub narzędzie wysyła przez powyższe ustawienia SMTP, w tym Go net/smtp, Ruby, Java, Laravel, Rails, Django, WordPress i n8n.

Migracja od innego dostawcy

Najszybsza migracja to SMTP: zmień host i poświadczenia, resztę pozostaw bez zmian. W każdym przypadku najpierw dodaj i zweryfikuj domenę wysyłki w onesend, ponieważ wysyłka wymaga zweryfikowanej domeny.

Amazon SES

Dla SMTP zmień host z email-smtp.REGION.amazonaws.com na smtp.onesend.eu na porcie 587 i użyj swojego key ID oraz key secret onesend zamiast poświadczeń SMTP SES. Jest to gotowe do użycia. Dla REST SES używa żądań podpisanych SigV4, więc API REST onesend ma inny kształt; przejdź na POST /v1/email/send albo użyj SMTP, aby zmigrować bez zmian w kodzie. Możesz wyeksportować listę wykluczeń SES i zaimportować plik CSV w panelu.

SendGrid

Dla SMTP SendGrid używa smtp.sendgrid.net z nazwą użytkownika apikey. onesend używa smtp.onesend.eu, z nazwą użytkownika ustawioną na Twój key ID i hasłem na Twój key secret. Dla REST /v3/mail/send SendGrida używa innej struktury JSON; użyj zamiast tego POST /v1/email/send onesend.

Mailgun

Dla SMTP zmień host z smtp.mailgun.org na smtp.onesend.eu i podmień poświadczenia. Dla REST Mailgun używa żądań kodowanych formularzowo do /v3/DOMAIN/messages; użyj zamiast tego JSON POST /v1/email/send onesend.

Postmark

Dla SMTP zmień host z smtp.postmarkapp.com na smtp.onesend.eu i podmień poświadczenia. Dla REST Postmark używa nagłówka X-Postmark-Server-Token i innej treści; użyj zamiast tego POST /v1/email/send onesend.

Wartości statusu dostarczenia

Wiadomość przechodzi przez następujące statusy:

• queued przyjęta i oczekuje na wysłanie przez workera.
• sent przekazana do serwera pocztowego odbiorcy.
• bounced twardy odrzut (trwały). Adres trafia na Twoją listę wykluczeń.
• soft_bounced błąd tymczasowy, np. pełna skrzynka. Ponawiane, bez wykluczenia.
• complained odbiorca oznaczył wiadomość jako spam. Dodany do Twojej listy wykluczeń.
• suppressed odbiorca był już na Twojej liście wykluczeń. Pominięty, nienaliczany.
• invalid adres nie przeszedł walidacji przed wysyłką (błędna składnia lub martwa domena).
• blocked zablokowany przez kontrolę zasad przed wysyłką.
• failed wewnętrzny błąd wysyłki.

Lista wykluczeń

onesend prowadzi listę wykluczeń dla każdego konta. Adresy trafiają na nią automatycznie po twardych odrzutach i skargach, po walidacji przed wysyłką, albo dodajesz je samodzielnie. onesend zapisuje zarówno powód (dlaczego wykluczony), jak i źródło (jak się tam znalazł) oraz rzeczywisty kod diagnostyczny. Listą zarządzasz w panelu i możesz ją importować lub eksportować jako CSV.

Plany i rozliczenia

Do wysyłki potrzebna jest zweryfikowana domena i plan. Okres próbny obejmuje 100 e-maili bez limitu czasu. Płatne plany to Starter i Growth, rozliczane miesięcznie przez Mollie (unijnego dostawcę płatności), z poprawnie naliczanym VAT dla klientów z UE i spoza UE, w tym z odwrotnym obciążeniem dla zweryfikowanych firmowych numerów VAT z UE. Nadwyżka jest naliczana, a nie blokowana, a wysyłki wykluczone nigdy nie są liczone. Aktualne ceny i wliczone wolumeny znajdziesz na stronie cennika.

Suwerenność i zgodność

• Podmiot prowadzący: WOCOO Management and Consulting GmbH, Wiedeń, Austria.
• Infrastruktura: Hetzner, Falkenstein, Niemcy. Brak amerykańskich podprocesorów w ścieżce wysyłki.
• Zbudowane pod RODO: dane odbiorców znajdują się w sejfie tożsamości, oddzielonym od logów wysyłki, a każde konto ustala własną politykę przechowywania. Dane listy wykluczeń i statystyki zbiorcze są zachowywane.
• Dostarczalność: SPF, DKIM z kluczami 2048-bitowymi na domenę oraz DMARC na domenę wysyłki. Dedykowane adresy IP wysyłki na życzenie.