SDKs
Die BillionSend-SDKs für Node.js, Python, Go, Ruby, PHP, Rust, Java, .NET und Elixir sowie die REST-API für jede andere Sprache.
Die eigenen SDKs von BillionSend decken jeden Endpunkt der API-Referenz ab, einschließlich Empfang und Postfächern. Jedes liest den API-Schlüssel aus BILLIONSEND_API_KEY und, wenn gesetzt, die API-URL aus BILLIONSEND_BASE_URL. Standard ist https://api.billionsend.com.
| Sprache | Paket | 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"} in mix.exs |
export BILLIONSEND_API_KEY=bs_...
Node.js / TypeScript
Node 18 oder neuer.
npm install @billionsend/node
import { BillionSend } from "@billionsend/node";
const bs = new BillionSend(); // liest 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);
Methoden werfen nie eine Ausnahme: Jede liefert { data, error, headers }. Die Anfragefelder behalten die Namen der API (reply_to, scheduled_at). Wiederholungsversuche, Idempotenzschlüssel, Postfach-Ereignisse und die Webhook-Verifizierung stehen auf der Seite Node.js-SDK.
Python
Python 3.11 oder neuer.
pip install billionsend
from billionsend import BillionSend
client = BillionSend() # liest 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"])
Ein fehlgeschlagener Aufruf löst eine Unterklasse von BillionSendError aus. AsyncBillionSend hat dieselben Methoden für asyncio. Mehr dazu auf der Seite Python-SDK.
Go
Go 1.23 oder neuer.
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() // liest 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)
}
Ein fehlgeschlagener Aufruf liefert einen Fehler, der sich zu *billionsend.Error entpacken lässt. Optionale Felder sind Zeiger (billionsend.String, Int64, Bool). Mehr dazu auf der Seite Go-SDK.
Ruby
Ruby 3.1 oder neuer.
gem install billionsend
require "billionsend"
client = BillionSend::Client.new # liest 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"]}"
Antworten sind Hashes mit String-Schlüsseln und den Feldnamen der API (sent["id"]), und ein fehlgeschlagener Aufruf löst eine Unterklasse von BillionSend::Error aus. Mehr dazu auf der Seite Ruby-SDK.
PHP
PHP 8.1 oder neuer.
composer require billionsend/billionsend-php:^0.1
use BillionSend\Client;
$client = new Client(); // liest 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";
Bodies und Antworten sind assoziative Arrays mit den Feldnamen der API, und ein fehlgeschlagener Aufruf wirft eine Unterklasse von BillionSendError. Mehr dazu auf der Seite PHP-SDK.
Rust
Rust 1.85 oder neuer, mit 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(); // liest 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(())
}
Ein fehlgeschlagener Aufruf liefert einen billionsend::Error, eine Variante je Art (NotFound, RateLimit, …). Bodies sind alles, was serde::Serialize umsetzt, etwa json!, und Antworten sind serde_json::Value, sofern Sie sie nicht mit .json::<T>() in Ihren eigenen Typ lesen. Mehr dazu auf der Seite Rust-SDK.
Java
Java 17 oder neuer. Mit 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(); // liest 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());
}
}
Ein fehlgeschlagener Aufruf wirft eine ungeprüfte Unterklasse von BillionSendException. Bodies sind jeder Wert, den Jackson schreiben kann, etwa eine Map mit den Feldnamen der API, und Antworten sind JsonNode-Bäume. Mehr dazu auf der Seite Java-SDK.
.NET
.NET 8 oder neuer.
dotnet add package BillionSend --version 0.1.0
using BillionSend;
using var client = new BillionSendClient(); // liest 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"]}");
Methoden sind asynchron (SendAsync), und Antworten sind JsonNode-Bäume mit den Feldnamen der API. Ein fehlgeschlagener Aufruf wirft eine Unterklasse von BillionSendException. Mehr dazu auf der Seite .NET-SDK.
Elixir
Elixir 1.18 oder neuer, mit OTP 25 oder neuer. In mix.exs:
def deps do
[{:billionsend, "~> 0.1"}]
end
client = BillionSend.client() # liest 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"]}")
Jede Funktion liefert {:ok, answer} oder {:error, error}, und ihr Gegenstück mit ! löst einen Fehler aus. Antworten sind Maps mit String-Schlüsseln und den Feldnamen der API. Mehr dazu auf der Seite Elixir-SDK.
Andere Sprachen: cURL
Aus jeder anderen Sprache rufen Sie die REST-API mit einem beliebigen HTTP-Client und demselben Schlüssel auf:
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>"
}'
Die Antwort ist { "id": "..." }. Ein Idempotency-Key macht einen erneuten Versuch nach einem Timeout sicher: Eine Wiederholung mit demselben Schlüssel und demselben Body liefert die erste Antwort, statt erneut zu senden. Authentifizierung, Fehler, Limits und Paginierung stehen unter API-Grundlagen, und jeder Endpunkt mit seinen Feldern steht in der API-Referenz.
Kommandozeile
@billionsend/cli 0.2.5 überträgt ein Konto von einem anderen Anbieter zu BillionSend. Es ist ein Migrationswerkzeug, kein Client zum Senden.