SDKs
Los SDKs de BillionSend para Node.js, Python, Go, Ruby, PHP, Rust, Java, .NET y Elixir, y la API REST para cualquier otro lenguaje.
Los SDKs propios de BillionSend cubren todos los endpoints de la referencia de la API, incluidas la recepción y las bandejas de entrada. Cada uno lee la clave de API de BILLIONSEND_API_KEY y, si está definida, la URL de la API de BILLIONSEND_BASE_URL; el valor por defecto es https://api.billionsend.com.
| Lenguaje | Paquete | Instalación |
|---|---|---|
| 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"} en mix.exs |
export BILLIONSEND_API_KEY=bs_...
Node.js / TypeScript
Node 18 o posterior.
npm install @billionsend/node
import { BillionSend } from "@billionsend/node";
const bs = new BillionSend(); // lee 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);
Los métodos nunca lanzan excepciones: cada uno se resuelve en { data, error, headers }. Los campos de la petición mantienen los nombres de la API (reply_to, scheduled_at). Los reintentos, las claves de idempotencia, los eventos de las bandejas de entrada y la verificación de webhooks están en la página del SDK de Node.js.
Python
Python 3.11 o posterior.
pip install billionsend
from billionsend import BillionSend
client = BillionSend() # lee 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"])
Una llamada que falla lanza una subclase de BillionSendError. AsyncBillionSend tiene los mismos métodos para asyncio. Más en la página del SDK de Python.
Go
Go 1.23 o posterior.
go get github.com/billionsend/billionsend-go
package main
import (
"context"
"fmt"
"log"
"github.com/billionsend/billionsend-go"
)
func main() {
ctx := context.Background()
client := billionsend.NewClient() // lee 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)
}
Una llamada que falla devuelve un error que se desenvuelve en *billionsend.Error. Los campos opcionales son punteros (billionsend.String, Int64, Bool). Más en la página del SDK de Go.
Ruby
Ruby 3.1 o posterior.
gem install billionsend
require "billionsend"
client = BillionSend::Client.new # lee 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"]}"
Las respuestas son Hashes con claves string y los nombres de campo de la API (sent["id"]), y una llamada que falla lanza una subclase de BillionSend::Error. Más en la página del SDK de Ruby.
PHP
PHP 8.1 o posterior.
composer require billionsend/billionsend-php:^0.1
use BillionSend\Client;
$client = new Client(); // lee 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";
Los cuerpos y las respuestas son arrays asociativos con los nombres de campo de la API, y una llamada que falla lanza una subclase de BillionSendError. Más en la página del SDK de PHP.
Rust
Rust 1.85 o posterior, con tokio.
cargo add billionsend 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(); // lee 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(())
}
Una llamada que falla devuelve un billionsend::Error, con una variante para cada tipo (NotFound, RateLimit, …). Los cuerpos pueden ser cualquier serde::Serialize, como json!, y las respuestas son serde_json::Value salvo que las leas en tu propio tipo con .json::<T>(). Más en la página del SDK de Rust.
Java
Java 17 o posterior. Con 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(); // lee 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());
}
}
Una llamada que falla lanza una subclase no comprobada de BillionSendException. Los cuerpos pueden ser cualquier valor que Jackson sepa escribir, como un Map con los nombres de campo de la API, y las respuestas son árboles JsonNode. Más en la página del SDK de Java.
.NET
.NET 8 o posterior.
dotnet add package BillionSend --version 0.1.0
using BillionSend;
using var client = new BillionSendClient(); // lee 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"]}");
Los métodos son asíncronos (SendAsync) y las respuestas son árboles JsonNode con los nombres de campo de la API. Una llamada que falla lanza una subclase de BillionSendException. Más en la página del SDK de .NET.
Elixir
Elixir 1.18 o posterior, con OTP 25 o posterior. En mix.exs:
def deps do
[{:billionsend, "~> 0.1"}]
end
client = BillionSend.client() # lee 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"]}")
Cada función devuelve {:ok, answer} o {:error, error}, y su gemela con ! lanza una excepción. Las respuestas son maps con claves string y los nombres de campo de la API. Más en la página del SDK de Elixir.
Otros lenguajes: cURL
Desde cualquier otro lenguaje, llama a la API REST con cualquier cliente HTTP y la misma clave:
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>"
}'
La respuesta es { "id": "..." }. Una Idempotency-Key hace seguro un reintento tras un tiempo de espera agotado: una repetición con la misma clave y el mismo cuerpo devuelve la primera respuesta en lugar de enviar de nuevo. La autenticación, los errores, los límites y la paginación están en los Conceptos básicos de la API, y cada endpoint con sus campos está en la referencia de la API.
Línea de comandos
La @billionsend/cli 0.2.5 traslada una cuenta desde otro proveedor a BillionSend. Es una herramienta de migración, no un cliente de envío.