Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

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.

¿Te ha resultado útil esta página?