Sviluppatori · Riferimento API
Documentazione API
Riferimento tecnico delle API HTTP Sendarix, autenticazione e pattern di integrazione comuni. Panoramica prodotto: API e-mail.
# Invia un’email critica tramite routing policy curl -sS -X POST 'https://app.sendarix.com/v1/email/send' \ -H 'Content-Type: application/json' \ -H 'X-API-Key: YOUR_API_KEY' \ -H 'Idempotency-Key: otp_8842' \ -d '{"to":"user@acme.com","template":"password_reset","routing_policy":"transactional-critical"}'
const sendarix = require("sendarix")(process.env.SENDARIX_KEY); await sendarix.email.send({ to: "user@acme.com", template: "password_reset", routingPolicy: "transactional-critical", idempotencyKey: "otp_8842" });
# SMTP drop-in — mantieni l’integrazione e ottieni un control plane host: smtp.sendarix.com port: 587 (STARTTLS) username: "your_sending_key" header: X-Sendarix-Policy: transactional-critical
Audit capacità (questa piattaforma)
I conteggi qui sotto riflettono ciò che l'applicazione espone oggi agli integratori. Qualsiasi linguaggio in grado di HTTPS + JSON può chiamare questi endpoint; la pagina include sei stack di esempio pronti per copia-incolla.
5
Superfici di integrazione
6
Linguaggi di esempio
6
Pattern di utilizzo
Superfici: (1) invio transazionale REST, (2) ingestione alert client REST, (3) Deliverability Intel REST, (4) relay SMTP (protocollo, non JSON), (5) webhook di engagement in uscita (ricevi POST HTTPS da Sendarix). Endpoint di sessione dashboard come GET /api/keys sono flussi browser/sessione, non automazione X-API-Key.
Superfici di integrazione
| Superficie | Meccanismo | Base / ingresso |
|---|---|---|
| Invio transazionale | POST JSON, chiave API account | POST /v1/email/send (alias /v1/send) |
| Alert client | POST JSON, stesso middleware chiave dell'invio | POST /v1/alerts/ingest |
| Deliverability Intel | GET/POST JSON, chiave API deliverability workspace | /api/deliverability/v1/* (7 route) |
| Relay SMTP | SMTP AUTH (host, porta, utente, password dalla dashboard) | Vedi SMTP relay |
| Webhook di engagement | Il tuo endpoint HTTPS riceve POST firmati | Configura nell'app → Webhook |
Autenticazione
- Chiave API account (invio + alert): header
X-API-Key: …oAuthorization: Bearer …. Query opzionale?api_key=supportata per strumenti; si raccomandano gli header. - Chiave API deliverability: header
X-API-Key(ambito workspace; emessa per Intel / monitor deliverability). - Idempotenza (invio): header opzionale
Idempotency-Keyper retry sicuri.
Le chiavi sono create e ruotate dalla dashboard cliente (gestione API). Le modalità di scope sono descritte nella policy interna di scope per chiavi limitate.
API di invio
POST https://app.sendarix.com/v1/email/send
Campi JSON del body (obbligatori salvo indicazione):
from— indirizzo mittente verificatoto— stringa o array di indirizzisubjecthtmle/otext— ci si aspetta almeno un body non vuoto (testo plain può derivare da HTML)
to, ma il percorso di trasporto attuale consegna al primo destinatario. Per consegne distinte multiple, una richiesta per destinatario (o SMTP per workflow multi-RCPT).Le risposte di successo includono identificatori come message_id e sx_trace_id per correlazione con log e webhook.
Ingestione alert client
POST https://app.sendarix.com/v1/alerts/ingest
Campi JSON tipici: event_type, severity (info, warning, critical), source, message, opzionalmente entity_type, entity_id, context (oggetto). La consegna dipende dalle regole alert configurate nella dashboard.
API Deliverability Intel
Base: /api/deliverability/v1/. Endpoint: workspace, client, domini, stato blacklist e generazione report. Tutti richiedono la chiave API deliverability workspace.
GET | /workspaces |
GET | /clients |
POST | /clients |
GET | /domains |
POST | /domains |
GET | /blacklists/status |
POST | /reports/generate |
Relay SMTP e webhook in stile inbound
SMTP usa submission mail standard con credenziali dalla dashboard — adatto a app legacy e MTA. Webhook di engagement sono in uscita da Sendarix verso il tuo URL per eventi di consegna e engagement (vedi pagina prodotto per payload e sicurezza).
Webhook inbound lato provider (es. Postal) sono endpoint infrastruttura, non target di integrazione cliente.
API di invio — esempi (6 linguaggi)
Sostituisci YOUR_API_KEY e gli indirizzi. Stesso JSON per ogni stack.
# Bash — invio transazionale
curl -sS -X POST 'https://app.sendarix.com/v1/email/send' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Idempotency-Key: order-10042-reset' \
-d '{
"from": "noreply@example.com",
"to": "user@example.com",
"subject": "Reimpostazione password",
"text": "Usa questo link per reimpostare la password.",
"html": "<p>Usa questo link per reimpostare la password.</p>"
}'// Node 18+ (fetch globale)
const res = await fetch('https://app.sendarix.com/v1/email/send', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'YOUR_API_KEY',
'Idempotency-Key': 'order-10042-reset',
},
body: JSON.stringify({
from: 'noreply@example.com',
to: 'user@example.com',
subject: "Reimpostazione password",
text: "Usa questo link per reimpostare la password.",
html: "<p>Usa questo link per reimpostare la password.<\/p>",
}),
});
console.log(await res.json());# Python 3
import json, urllib.request
req = urllib.request.Request(
'https://app.sendarix.com/v1/email/send',
data=json.dumps({
'from': 'noreply@example.com',
'to': 'user@example.com',
'subject': "Reimpostazione password",
'text': "Usa questo link per reimpostare la password.",
'html': "<p>Usa questo link per reimpostare la password.<\/p>",
}).encode(),
headers={
'Content-Type': 'application/json',
'X-API-Key': 'YOUR_API_KEY',
'Idempotency-Key': 'order-10042-reset',
},
method='POST',
)
with urllib.request.urlopen(req) as r:
print(r.read().decode())<?php
$ch = curl_init('https://app.sendarix.com/v1/email/send');
$payload = json_encode([
'from' => 'noreply@example.com',
'to' => 'user@example.com',
'subject' => 'Reimpostazione password',
'text' => 'Usa questo link per reimpostare la password.',
'html' => '<p>Usa questo link per reimpostare la password.</p>',
]);\ncurl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: YOUR_API_KEY',
'Idempotency-Key: order-10042-reset',
],
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);// Go
package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
body, _ := json.Marshal(map[string]any{
"from": "noreply@example.com",
"to": "user@example.com",
"subject": "Reimpostazione password",
"text": "Usa questo link per reimpostare la password.",
"html": "<p>Usa questo link per reimpostare la password.<\/p>",
})
req, _ := http.NewRequest("POST", "https://app.sendarix.com/v1/email/send", bytes.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "YOUR_API_KEY")
req.Header.Set("Idempotency-Key", "order-10042-reset")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
}# Ruby — net/http
require 'json'
require 'net/http'
uri = URI('https://app.sendarix.com/v1/email/send')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['X-API-Key'] = 'YOUR_API_KEY'
req['Idempotency-Key'] = 'order-10042-reset'
req.body = {
from: 'noreply@example.com',
to: 'user@example.com',
subject: "Reimpostazione password",
text: "Usa questo link per reimpostare la password.",
html: "<p>Usa questo link per reimpostare la password.<\/p>",
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body Pattern di utilizzo (6)
- Invio singolo — un POST per messaggio, senza header idempotenza.
- Retry idempotente — stesso
Idempotency-Key+ body su fallimenti di rete. - Auth Bearer — sostituisci
X-API-KeyconAuthorization: Bearer YOUR_API_KEY. - HTML + text — fornisci entrambi per rendering multipart/alternative dove supportato.
- Fan-out alert — POST a
/v1/alerts/ingestdai monitor; l'instradamento è guidato da policy nell'UI. - Automazione deliverability — polling o mutazione risorse Intel sotto
/api/deliverability/v1/*con la chiave workspace.
Correlati
Protege email crítico en cada tenant.
Mueve tu stream más crítico a Sendarix esta semana. Deja todo lo demás exactamente donde está.
