Como enviar e-mail via API: PHP, Node, Python, Go

Como enviar e-mail via 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.

Obtenha uma chave de API e verifique seu domínio

Crie uma chave no painel em "Chaves de API" — cada chave possui escopos como messages:send. Você só pode enviar de um endereço em um domínio verificado: adicione o domínio, publique SPF, DKIM e DMARC, e aguarde o status verificado. Veja a documentação e verifique um domínio gratuitamente no laboratório de entregabilidade.

Início rápido: 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": "Bem-vindo!",
    "html": "<h1>Olá</h1><p>Obrigado por se inscrever.</p>",
    "stream": "transactional"
  }'

Uma resposta bem-sucedida é HTTP 202:

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

PHP

Baixe o SDK de arquivo único de /sdk/yourtrend.php — sem dependências, apenas a extensão cURL.

<?php
require 'yourtrend.php';

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

if ($res['status'] === 202) {
    echo 'Na fila: ' . $res['data']['data']['id'];
} else {
    echo 'Erro: ' . ($res['data']['error']['message'] ?? 'desconhecido');
}

Node.js

O /sdk/yourtrend.js SDK usa o fetch embutido (Node 18+) e não precisa de pacotes externos.

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

const { status, data } = await yt.sendEmail(
  'noreply@yourdomain.com',
  'user@example.com',
  'Bem-vindo!',
  '<h1>Olá</h1>'
);

if (status === 202) console.log('Na fila:', data.data.id);
else console.error('Erro:', data.error?.message);

Python

O /sdk/yourtrend.py SDK é uma biblioteca padrão pura (urllib) — nada para instalar.

from yourtrend import YourTrend

yt = YourTrend('YOUR_API_KEY')
res = yt.send_email(
    'noreply@yourdomain.com',
    'user@example.com',
    'Bem-vindo!',
    '<h1>Olá!</h1>',
)

if res['status'] == 202:
    print('Na fila:', res['data']['data']['id'])
else:
    print('Erro:', res['data']['error']['message'])

Ir

package main

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

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

Campos extras

O corpo da solicitação aceita mais do que os quatro básicos:

texto — uma alternativa em texto simples (recomendada junto com html).
cc, bcc, reply_to — arrays de endereços ou uma string separada por vírgulas.
stream — transacional ou em massa: dividir streams protege sua reputação de IP.
anexos — um array de {nome_arquivo, conteúdo, tipo_conteúdo} objetos, com conteúdo codificado em base64.
template_id + variáveis — envie um template armazenado com substituições de mesclagem.
enviar_em — um timestamp ISO-8601 para entrega agendada.

Idempotência e modo de teste

Adicione um Idempotency-Key: <uuid> header — em uma nova tentativa da mesma solicitação (por exemplo, após um timeout) o YourTrend retorna a primeira resposta em vez de enviar um duplicado. O X-Test-Mode: true header executa a solicitação sem entrega real e sem consumir cota — útil em CI.

Tratando erros

Todo erro de API chega em um envelope:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Limite diário de envio alcançado.",
    "request_id": "0f9d…"
  }
}

Verifique o status HTTP, não apenas o corpo. Códigos comuns: 401 — chave inválida; 422 — erro de validação (um campo erros lista o problema por campo); 429 — limite de taxa, tente novamente com backoff exponencial; 402/quota_exceeded — cota do plano esgotada. Para trabalhos em massa, use POST /api/v1/messages/batch (até 1000 mensagens, uma resposta 207 com status por mensagem).

Quer um wrapper para sua pilha? Os SDKs do YourTrend para PHP, Node, Python e Go são um arquivo sem dependências cada — copie-os diretamente para seu projeto. A lista completa de endpoints e campos está na documentação da API, e os níveis de volume estão na página de preços.

Verificando status e webhooks

Uma vez na fila, você pode ler o status de uma mensagem com GET /api/v1/messages/{id} — a resposta traz status (na fila, enviado, entregue, devolvido, reclamado) além de contagens de aberturas e reclamações. Fazer polling na API por mensagem é desperdício, então conecte webhooks para eventos de entrega: o YourTrend envia um POST para sua URL ao ser entregue, aberto, clicado, devolvido e reclamado. Cada chamada é assinada com HMAC em um header — verifique a assinatura para rejeitar falsificações, e responda 2xx dentro de alguns segundos; em caso de falha, o webhook é tentado novamente com backoff crescente (uma fila de tentativas). É assim que você constrói um tratamento robusto de falhas: devoluções duras vão para a lista de supressão, reclamações recebem uma reação imediata, e suas próprias análises se acumulam sem polling manual. A lista completa de tipos de eventos e a forma do payload estão na documentação, e os níveis de envio estão na página de preços.

Como enviar e-mail via API: PHP, Node, Python, Go