SDKs
The BillionSend SDKs for Node.js, Python, Go, Ruby, PHP, Rust, Java, .NET and Elixir, and the REST API for every other language.
BillionSend’s own SDKs cover every endpoint of the API reference, receiving and inboxes included. Each reads the API key from BILLIONSEND_API_KEY and, when set, the API URL from BILLIONSEND_BASE_URL; the default is https://api.billionsend.com.
| Language | Package | Install |
|---|---|---|
| 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 or newer.
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);
Methods never throw: each resolves to { data, error, headers }. Request fields keep the API’s names (reply_to, scheduled_at). Retries, idempotency keys, inbox events and webhook verification are on the Node.js SDK page.
Python
Python 3.11 or newer.
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"])
A failed call raises a BillionSendError subclass. AsyncBillionSend has the same methods for asyncio. More on the Python SDK page.
Go
Go 1.23 or newer.
go get github.com/billionsend/billionsend-go@v0.1.3
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)
}
A failed call returns an error that unwraps to *billionsend.Error. Optional fields are pointers (billionsend.String, Int64, Bool). More on the Go SDK page.
Ruby
Ruby 3.1 or newer.
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"]}"
Answers are Hashes with string keys and the API’s field names (sent["id"]), and a failed call raises a BillionSend::Error subclass. More on the Ruby SDK page.
PHP
PHP 8.1 or newer.
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";
Bodies and answers are associative arrays with the API’s field names, and a failed call throws a BillionSendError subclass. More on the PHP SDK page.
Rust
Rust 1.85 or newer, with tokio.
cargo add billionsend@0.1.2 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(())
}
A failed call returns a billionsend::Error, one variant per kind (NotFound, RateLimit, …). Bodies are anything serde::Serialize, such as json!, and answers are serde_json::Value unless you read them into your own type with .json::<T>(). More on the Rust SDK page.
Java
Java 17 or newer. With 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());
}
}
A failed call throws an unchecked BillionSendException subclass. Bodies are any value Jackson can write, such as a Map with the API’s field names, and answers are JsonNode trees. More on the Java SDK page.
.NET
.NET 8 or newer.
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"]}");
Methods are async (SendAsync) and answers are JsonNode trees with the API’s field names. A failed call throws a BillionSendException subclass. More on the .NET SDK page.
Elixir
Elixir 1.18 or newer, with OTP 25 or newer. In 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"]}")
Every function returns {:ok, answer} or {:error, error}, and its ! twin raises. Answers are maps with string keys and the API’s field names. More on the Elixir SDK page.
Other languages: cURL
From any other language, call the REST API with any HTTP client and the same key:
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>"
}'
The answer is { "id": "..." }. An Idempotency-Key makes a retry after a timeout safe: a repeat with the same key and body returns the first answer instead of sending again. Authentication, errors, limits and pagination are on API basics, and every endpoint with its fields is in the API reference.
Command line
@billionsend/cli 0.2.5 moves an account from another provider to BillionSend. It is a migration tool, not a sending client.