SDKs
Les SDKs BillionSend pour Node.js, Python, Go, Ruby, PHP, Rust, Java, .NET et Elixir, et l'API REST pour tous les autres langages.
Les SDKs de BillionSend couvrent tous les endpoints de la référence de l’API, réception et boîtes de réception comprises. Chacun lit la clé API dans BILLIONSEND_API_KEY et, si elle est définie, l’URL de l’API dans BILLIONSEND_BASE_URL ; par défaut, c’est https://api.billionsend.com.
| Langage | Paquet | Installation |
|---|---|---|
| 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"} dans mix.exs |
export BILLIONSEND_API_KEY=bs_...
Node.js / TypeScript
Node 18 ou plus récent.
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);
Les méthodes ne lèvent jamais d’exception : chacune se résout en { data, error, headers }. Les champs de requête gardent les noms de l’API (reply_to, scheduled_at). Les nouvelles tentatives, les clés d’idempotence, les événements de boîte de réception et la vérification des webhooks sont décrits sur la page SDK Node.js.
Python
Python 3.11 ou plus récent.
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"])
Un appel en échec lève une sous-classe de BillionSendError. AsyncBillionSend a les mêmes méthodes pour asyncio. Plus de détails sur la page SDK Python.
Go
Go 1.23 ou plus récent.
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() // 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)
}
Un appel en échec renvoie une erreur qui se déballe en *billionsend.Error. Les champs facultatifs sont des pointeurs (billionsend.String, Int64, Bool). Plus de détails sur la page SDK Go.
Ruby
Ruby 3.1 ou plus récent.
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"]}"
Les réponses sont des Hashes à clés chaîne avec les noms de champs de l’API (sent["id"]), et un appel en échec lève une sous-classe de BillionSend::Error. Plus de détails sur la page SDK Ruby.
PHP
PHP 8.1 ou plus récent.
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";
Les corps de requête et les réponses sont des tableaux associatifs avec les noms de champs de l’API, et un appel en échec lève une sous-classe de BillionSendError. Plus de détails sur la page SDK PHP.
Rust
Rust 1.85 ou plus récent, avec 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(); // 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(())
}
Un appel en échec renvoie un billionsend::Error, avec une variante par type d’erreur (NotFound, RateLimit, …). Les corps de requête sont tout ce qui implémente serde::Serialize, comme json!, et les réponses sont des serde_json::Value, sauf si vous les lisez dans votre propre type avec .json::<T>(). Plus de détails sur la page SDK Rust.
Java
Java 17 ou plus récent. Avec 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());
}
}
Un appel en échec lève une sous-classe non vérifiée de BillionSendException. Les corps de requête sont toute valeur que Jackson sait écrire, comme une Map avec les noms de champs de l’API, et les réponses sont des arbres JsonNode. Plus de détails sur la page SDK Java.
.NET
.NET 8 ou plus récent.
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"]}");
Les méthodes sont asynchrones (SendAsync) et les réponses sont des arbres JsonNode avec les noms de champs de l’API. Un appel en échec lève une sous-classe de BillionSendException. Plus de détails sur la page SDK .NET.
Elixir
Elixir 1.18 ou plus récent, avec OTP 25 ou plus récent. Dans 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"]}")
Chaque fonction renvoie {:ok, answer} ou {:error, error}, et sa jumelle en ! lève une exception. Les réponses sont des maps à clés chaîne avec les noms de champs de l’API. Plus de détails sur la page SDK Elixir.
Autres langages : cURL
Depuis n’importe quel autre langage, appelez l’API REST avec n’importe quel client HTTP et la même clé :
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 réponse est { "id": "..." }. Une Idempotency-Key rend sûre une nouvelle tentative après un délai dépassé : une répétition avec la même clé et le même corps renvoie la première réponse au lieu d’envoyer de nouveau. L’authentification, les erreurs, les limites et la pagination sont décrites dans Notions de base de l’API, et chaque endpoint avec ses champs figure dans la référence de l’API.
Ligne de commande
@billionsend/cli 0.2.5 fait passer un compte d’un autre fournisseur vers BillionSend. C’est un outil de migration, pas un client d’envoi.