Come inviare email tramite API: PHP, Node, Python, Go

Come inviare un'email tramite API

To send an email through the YourTrend API, make a POST request to https://yourtrend.online/api/v1/messages with an Authorization: Bearer YOUR_API_KEY header and a JSON body containing from, to, subject and html. The server responds 202 Accepted, queues the message and signs it with DKIM. Below are working examples in curl and four SDKs.

Ottieni una chiave API e verifica il tuo dominio

Crea una chiave nel pannello sotto "Chiavi API" — ogni chiave ha ambiti come messages:send. Puoi inviare solo da un indirizzo su un dominio verificato: aggiungi il dominio, pubblica SPF, DKIM e DMARC, e attendi lo stato verificato. Consulta la documentazione e controlla un dominio gratuitamente nel laboratorio di deliverability.

Inizio rapido: curl

curl -X POST https://yourtrend.online/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "Benvenuto!",
    "html": "<h1>Ciao!</h1><p>Grazie per esserti registrato.</p>",
    "stream": "transactional"
  }'

Una risposta di successo è HTTP 202:

{
  "data": {
    "id": "9b1c7e2a-1f3d-4b8a-9c11-4a2f6e8d0c33",
    "status": "in coda",
    "stream": "transactional",
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "Benvenuto!"
  }
}

PHP

Scarica l'SDK in un unico file da /sdk/yourtrend.php — nessuna dipendenza, solo l'estensione cURL.

<?php
require 'yourtrend.php';

$yt  = new YourTrend('YOUR_API_KEY');
$res = $yt->sendEmail(
    'noreply@yourdomain.com',
    'user@example.com',
    'Benvenuto!',
    '<h1>Ciao!</h1>'
);

if ($res['status'] === 202) {
    echo 'In coda: ' . $res['data']['data']['id'];
} else {
    echo 'Errore: ' . ($res['data']['error']['message'] ?? 'sconosciuto');
}

Node.js

L'SDK /sdk/yourtrend.js utilizza il fetch integrato (Node 18+) e non ha bisogno di pacchetti esterni.

const YourTrend = require('./yourtrend');
const yt = new YourTrend('YOUR_API_KEY');

const { status, data } = await yt.sendEmail(
  'noreply@yourdomain.com',
  'user@example.com',
  'Benvenuto!',
  '<h1>Ciao!</h1>'
);

if (status === 202) console.log('In coda:', data.data.id);
else console.error('Errore:', data.error?.message);

Python

Il /sdk/yourtrend.py SDK è una libreria standard pura (urllib) — nulla da installare.

from yourtrend import YourTrend

yt = YourTrend('YOUR_API_KEY')
res = yt.send_email(
    'noreply@yourdomain.com',
    'user@example.com',
    'Benvenuto!',
    '<h1>Ciao!</h1>',
)

if res['status'] == 202:
    print('In coda:', res['data']['data']['id'])
else:
    print('Errore:', res['data']['error']['message'])

Vai

package main

import (
    "fmt"
    "log"
    "yourtrend"
)

func main() {
    c := yourtrend.New("YOUR_API_KEY")
    resp, err := c.SendEmail(
        "noreply@yourdomain.com",
        "user@example.com",
        "Benvenuto!",
        "<h1>Ciao!</h1>",
    )
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    fmt.Println("HTTP", resp.StatusCode) // 202 = accettato
}

Campi extra

Il corpo della richiesta accetta più di quattro elementi di base:

• text — un'alternativa in testo semplice (consigliata insieme a html).
• cc, bcc, reply_to — array di indirizzi o una stringa separata da virgole.
• stream — transazionale o in blocco: suddividere i flussi protegge la tua reputazione IP.
• allegati — un array di {filename, content, content_type} oggetti, con content codificato in base64.
• template_id + variabili — invia un template memorizzato con sostituzioni di unione.
• send_at — un timestamp ISO-8601 per la consegna programmata.

Idempotenza e modalità di test

Aggiungi un Idempotency-Key: <uuid> header — in un tentativo di ripetere la stessa richiesta (ad esempio, dopo un timeout) YourTrend restituisce la prima risposta invece di inviare un duplicato. L'X-Test-Mode: true header esegue la richiesta senza consegna reale e senza consumare quota — utile in CI.

Gestione degli errori

Ogni errore API arriva in una busta:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Limite di invio giornaliero raggiunto.",
    "request_id": "0f9d…"
  }
}

Controlla lo stato HTTP, non solo il corpo. Codici comuni: 401 — chiave errata; 422 — errore di convalida (un campo errors elenca il problema per campo); 429 — limite di frequenza, riprova con backoff esponenziale; 402/quota_exceeded — quota del piano esaurita. Per lavori in blocco usa POST /api/v1/messages/batch (fino a 1000 messaggi, una risposta 207 con uno stato per messaggio).

Vuoi un wrapper per il tuo stack? Gli SDK di YourTrend per PHP, Node, Python e Go sono un file ciascuno senza dipendenze — copiali direttamente nel tuo progetto. L'elenco completo degli endpoint e dei campi si trova nella documentazione API, e i livelli di volume sono nella pagina prezzi.

Controllo dello stato e webhook

Una volta in coda, puoi leggere lo stato di un messaggio con GET /api/v1/messages/{id} — la risposta riporta status (in coda, inviato, consegnato, rimbalzato, lamentato) più conteggi di aperture e lamentele. Polling dell'API per messaggio è uno spreco, quindi collega i webhook per gli eventi di consegna: YourTrend invia un POST al tuo URL su consegnato, aperto, cliccato, rimbalzato e lamentato. Ogni chiamata è firmata HMAC in un header — verifica la firma per rifiutare le falsificazioni e rispondi 2xx entro pochi secondi; in caso di errore il webhook viene riprovato con un backoff crescente (una coda di ripetizione). Questo è come costruisci una gestione robusta degli errori: i rimbalzi duri vanno nella lista di soppressione, le lamentele ricevono una reazione immediata e le tue analisi si riempiono senza polling manuale. L'elenco completo dei tipi di eventi e la forma del payload sono nella documentazione, e i livelli di invio sono nella pagina prezzi.