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.