Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

SDKs

Os SDKs do BillionSend para Node.js, Python, Go, Ruby, PHP, Rust, Java, .NET e Elixir, e a API REST para todas as outras linguagens.

Os SDKs próprios do BillionSend cobrem todos os endpoints da referência da API, incluindo recebimento e caixas de entrada. Cada um lê a chave de API de BILLIONSEND_API_KEY e, quando definida, a URL da API de BILLIONSEND_BASE_URL; o padrão é https://api.billionsend.com.

Linguagem Pacote Instalação
Node.js @billionsend/node 0.1.1 npm install @billionsend/node
Python billionsend 0.1.1 pip install billionsend
Go github.com/billionsend/billionsend-go 0.1.3 go get github.com/billionsend/billionsend-go@v0.1.3
Ruby billionsend 0.1.0 gem install billionsend
PHP billionsend/billionsend-php 0.1.2 composer require billionsend/billionsend-php:^0.1
Rust billionsend 0.1.2 cargo add billionsend@0.1.2
Java com.billionsend:billionsend-java 0.1.2 implementation("com.billionsend:billionsend-java:0.1.2")
.NET BillionSend 0.1.0 dotnet add package BillionSend --version 0.1.0
Elixir billionsend 0.1.0 {:billionsend, "~> 0.1"} no mix.exs
export BILLIONSEND_API_KEY=bs_...

Node.js / TypeScript

Node 18 ou mais novo.

npm install @billionsend/node
import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.emails.send({
  from: "Acme <onboarding@acme.dev>",
  to: ["success@simulator.amazonses.com"],
  subject: "Hello from BillionSend",
  html: "<strong>It works!</strong>",
});

if (error) console.error(error.statusCode, error.name, error.message);
else console.log("sent", data.id);

Os métodos nunca lançam exceção: cada um resolve para { data, error, headers }. Os campos da requisição mantêm os nomes da API (reply_to, scheduled_at). Novas tentativas, chaves de idempotência, eventos das caixas de entrada e verificação de webhooks estão na página do SDK para Node.js.

Python

Python 3.11 ou mais novo.

pip install billionsend
from billionsend import BillionSend

client = BillionSend()  # reads BILLIONSEND_API_KEY

email = client.emails.send(
    {
        "from": "Acme <onboarding@acme.dev>",
        "to": ["success@simulator.amazonses.com"],
        "subject": "Hello from BillionSend",
        "html": "<strong>It works!</strong>",
    }
)
print(email["id"])

Uma chamada que falha lança uma subclasse de BillionSendError. AsyncBillionSend tem os mesmos métodos para asyncio. Mais na página do SDK para Python.

Go

Go 1.23 ou mais recente.

go get github.com/billionsend/billionsend-go@v0.1.3
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/billionsend/billionsend-go"
)

func main() {
	ctx := context.Background()
	client := billionsend.NewClient() // reads BILLIONSEND_API_KEY

	sent, err := client.Emails.Send(ctx, &billionsend.SendEmailRequest{
		From:    "Acme <onboarding@acme.dev>",
		To:      []string{"success@simulator.amazonses.com"},
		Subject: "Hello from BillionSend",
		HTML:    billionsend.String("<strong>It works!</strong>"),
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("sent", sent.ID)
}

Uma chamada que falha devolve um erro que se desembrulha em *billionsend.Error. Campos opcionais são ponteiros (billionsend.String, Int64, Bool). Mais na página do SDK para Go.

Ruby

Ruby 3.1 ou mais recente.

gem install billionsend
require "billionsend"

client = BillionSend::Client.new # reads BILLIONSEND_API_KEY

sent = client.emails.send({
  from: "Acme <onboarding@acme.dev>",
  to: ["success@simulator.amazonses.com"],
  subject: "Hello from BillionSend",
  html: "<strong>It works!</strong>"
})
puts "sent #{sent["id"]}"

As respostas são Hashes com chaves string e os nomes de campo da API (sent["id"]), e uma chamada que falha lança uma subclasse de BillionSend::Error. Mais na página do SDK para Ruby.

PHP

PHP 8.1 ou mais recente.

composer require billionsend/billionsend-php:^0.1
use BillionSend\Client;

$client = new Client(); // reads BILLIONSEND_API_KEY

$sent = $client->emails->send([
    'from' => 'Acme <onboarding@acme.dev>',
    'to' => ['success@simulator.amazonses.com'],
    'subject' => 'Hello from BillionSend',
    'html' => '<strong>It works!</strong>',
]);
echo 'sent ', $sent['id'], "\n";

Corpos e respostas são arrays associativos com os nomes de campo da API, e uma chamada que falha lança uma subclasse de BillionSendError. Mais na página do SDK para PHP.

Rust

Rust 1.85 ou mais recente, com tokio.

cargo add billionsend@0.1.2 serde_json
cargo add tokio --features macros,rt-multi-thread
use billionsend::BillionSend;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), billionsend::Error> {
    let bs = BillionSend::from_env(); // reads BILLIONSEND_API_KEY

    let sent = bs
        .emails()
        .send(&json!({
            "from": "Acme <onboarding@acme.dev>",
            "to": ["success@simulator.amazonses.com"],
            "subject": "Hello from BillionSend",
            "html": "<strong>It works!</strong>",
        }))
        .await?;
    println!("sent {}", sent["id"].as_str().unwrap_or_default());
    Ok(())
}

Uma chamada que falha devolve um billionsend::Error, com uma variante para cada tipo (NotFound, RateLimit, …). Os corpos são qualquer coisa serde::Serialize, como json!, e as respostas são serde_json::Value, a menos que você as leia no seu próprio tipo com .json::<T>(). Mais na página do SDK para Rust.

Java

Java 17 ou mais recente. Com Gradle (Maven: com.billionsend:billionsend-java:0.1.2):

implementation("com.billionsend:billionsend-java:0.1.2")
import com.billionsend.BillionSend;
import com.fasterxml.jackson.databind.JsonNode;
import java.util.List;
import java.util.Map;

public class Hello {
  public static void main(String[] args) {
    BillionSend client = new BillionSend(); // reads BILLIONSEND_API_KEY

    JsonNode sent =
        client.emails().send(
            Map.of(
                "from", "Acme <onboarding@acme.dev>",
                "to", List.of("success@simulator.amazonses.com"),
                "subject", "Hello from BillionSend",
                "html", "<strong>It works!</strong>"));
    System.out.println("sent " + sent.get("id").asText());
  }
}

Uma chamada que falha lança uma subclasse não verificada de BillionSendException. Corpos são qualquer valor que o Jackson consiga escrever, como um Map com os nomes de campo da API, e as respostas são árvores JsonNode. Mais na página do SDK para Java.

.NET

.NET 8 ou mais recente.

dotnet add package BillionSend --version 0.1.0
using BillionSend;

using var client = new BillionSendClient(); // reads BILLIONSEND_API_KEY

var sent = await client.Emails.SendAsync(new
{
    from = "Acme <onboarding@acme.dev>",
    to = new[] { "success@simulator.amazonses.com" },
    subject = "Hello from BillionSend",
    html = "<strong>It works!</strong>",
});
Console.WriteLine($"sent {sent?["id"]}");

Os métodos são assíncronos (SendAsync) e as respostas são árvores JsonNode com os nomes de campo da API. Uma chamada que falha lança uma subclasse de BillionSendException. Mais na página do SDK para .NET.

Elixir

Elixir 1.18 ou mais recente, com OTP 25 ou mais recente. No mix.exs:

def deps do
  [{:billionsend, "~> 0.1"}]
end
client = BillionSend.client()  # reads BILLIONSEND_API_KEY

{:ok, sent} =
  BillionSend.Emails.send(client, %{
    from: "Acme <onboarding@acme.dev>",
    to: ["success@simulator.amazonses.com"],
    subject: "Hello from BillionSend",
    html: "<strong>It works!</strong>"
  })

IO.puts("sent #{sent["id"]}")

Toda função devolve {:ok, answer} ou {:error, error}, e a sua gêmea com ! lança o erro. As respostas são mapas com chaves string e os nomes de campo da API. Mais na página do SDK para Elixir.

Outras linguagens: cURL

Em qualquer outra linguagem, chame a API REST com qualquer cliente HTTP e a mesma chave:

curl -X POST "https://api.billionsend.com/emails" \
  -H "Authorization: Bearer $BILLIONSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome/ana" \
  -d '{
    "from": "Acme <onboarding@acme.dev>",
    "to": ["success@simulator.amazonses.com"],
    "subject": "Hello from BillionSend",
    "html": "<strong>It works!</strong>"
  }'

A resposta é { "id": "..." }. Uma Idempotency-Key torna segura uma nova tentativa depois de um timeout: uma repetição com a mesma chave e o mesmo corpo devolve a primeira resposta em vez de enviar de novo. Autenticação, erros, limites e paginação estão em Básico da API, e cada endpoint com seus campos está na referência da API.

Linha de comando

@billionsend/cli 0.2.5 move uma conta de outro provedor para o BillionSend. É uma ferramenta de migração, não um cliente de envio.

Esta página foi útil?