Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

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.

Cette page vous a-t-elle été utile ?