# SDKs

> MailBlastr ships an official Node.js SDK (`mailblastr`), and its clean REST API can be called from any HTTP client.

MailBlastr ships an **official Node.js SDK** — the [`mailblastr`](https://www.npmjs.com/package/mailblastr) package on npm. It is the recommended way to call MailBlastr from JavaScript and TypeScript.

For other languages, MailBlastr exposes a **clean REST API**: predictable request and response shapes, `mb_`-prefixed API keys, the `Bearer` auth scheme, a consistent error envelope, and standard pagination conventions. So you have two good options: use the official Node SDK, or hit the JSON API directly with any HTTP client.

## Official Node.js SDK

Install the `mailblastr` package and instantiate the client with your `mb_` API key. Every method returns `{ data, error }` — `error` is `null` on success, or `{ statusCode, name, message }` on failure, so there are no exceptions to catch for API errors.

```bash
npm install mailblastr
```

**Send an email**

```ts
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.emails.send({
  from: 'Acme <hello@yourdomain.com>',
  to: ['user@example.com'],
  subject: 'Hello from MailBlastr',
  html: '<p>Your first email 🎉</p>',
});

if (error) console.error(error.name, error.message);
else console.log('sent', data.id);
```

The client exposes one property per resource — `emails` (with nested `emails.receiving`), `batch`, `domains`, `audiences`, `contacts`, `contactProperties`, `campaigns`, `segments`, `topics`, `templates`, `automations`, `webhooks`, `logs`, `events`, and `apiKeys` — each modeled on the same `create` / `get` / `list` / `update` shape used throughout these docs.

**Override the API host**

```ts
const mb = new MailBlastr('mb_xxxxxxxxx', {
  baseUrl: 'https://api.mailblastr.com', // optional — defaults to the MailBlastr host
});
```

> **Note:** The official SDK is Node-only. For other languages, use the REST API directly (below).

## Call the REST API directly

Every endpoint in these docs is plain JSON over HTTPS at `https://api.mailblastr.com`. Authenticate with an `Authorization: Bearer mb_xxxxxxxxx` header. Each API page shows ready-to-run **cURL**, **Node.js**, and **Python** examples.

**Node.js**

```js
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": ["user@example.com"],
  "subject": "Hello from MailBlastr",
  "html": "<p>It works!</p>"
});
console.log({ data, error });
```

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": [
    "user@example.com"
  ],
  "subject": "Hello from MailBlastr",
  "html": "<p>It works!</p>"
})
```

**PHP**

```php
$mailblastr = Mailblastr::client('mb_xxxxxxxxx');

$mailblastr->emails->send([
  'from' => "Acme <hello@yourdomain.com>",
  'to' => [
    "user@example.com"
  ],
  'subject' => "Hello from MailBlastr",
  'html' => "<p>It works!</p>"
]);
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": [
    "user@example.com"
  ],
  "subject": "Hello from MailBlastr",
  "html": "<p>It works!</p>"
})
```

**Go**

```go
import "github.com/shekhu10/mailblastr-sdks/mailblastr-go"

client := mailblastr.NewClient("mb_xxxxxxxxx")

params := &mailblastr.SendEmailRequest{
    From:    "Acme <hello@yourdomain.com>",
    To:      []string{"delivered@example.com"},
    Subject: "hello world",
    Html:    "<p>it works!</p>",
}
sent, err := client.Emails.Send(params)
```

**Rust**

```rust
use mailblastr::{Mailblastr, CreateEmailBaseOptions};

let mb = Mailblastr::new("mb_xxxxxxxxx");

let email = CreateEmailBaseOptions::new(
    "Acme <hello@yourdomain.com>",
    ["delivered@example.com"],
    "hello world",
).with_html("<p>it works!</p>");
let _sent = mb.emails.send(email).await?;
```

**Java**

```java
import com.mailblastr.*;

Mailblastr mailblastr = new Mailblastr("mb_xxxxxxxxx");

SendEmailRequest request = SendEmailRequest.builder()
    .from("Acme <hello@yourdomain.com>")
    .to("delivered@example.com")
    .subject("hello world")
    .html("<p>it works!</p>")
    .build();
mailblastr.emails().send(request);
```

**.NET**

```csharp
using Mailblastr;

IMailblastr mailblastr = MailblastrClient.Create("mb_xxxxxxxxx");

var resp = await mailblastr.EmailSendAsync(new EmailMessage
{
    From = "Acme <hello@yourdomain.com>",
    To = "delivered@example.com",
    Subject = "hello world",
    HtmlBody = "<p>it works!</p>",
});
```

**cURL**

```bash
curl -X POST 'https://api.mailblastr.com/emails' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@yourdomain.com>",
  "to": ["user@example.com"],
  "subject": "Hello from MailBlastr",
  "html": "<p>It works!</p>"
}'
```

**CLI**

```bash
mailblastr emails send \
  --from 'Acme <hello@yourdomain.com>' \
  --to 'user@example.com' \
  --subject 'Hello from MailBlastr' \
  --html '<p>It works!</p>'
```

> **Note:** Official SDKs ship for Go, Ruby, PHP, Python, Rust, Java, and .NET — and the API works identically from any other language with an HTTP client (Elixir, Kotlin, …).

## Any HTTP client works

Prefer no dependency? The API is plain JSON over HTTPS, so the standard HTTP client in any language can call it directly. Point your client at `https://api.mailblastr.com` with your `mb_` key and send a request:

- **Node.js** — the official `mailblastr` SDK, or the built-in `fetch`.
- **PHP** — Guzzle, or `curl` via the cURL extension.
- **Python** — `requests` or `httpx`.
- **Ruby** — `Net::HTTP` or `Faraday`.
- **Go** — `net/http`.
- **Java** — `java.net.http.HttpClient`.
- **Rust** — `reqwest`.
- **.NET** — `HttpClient`.

Each API reference page includes ready-to-run snippets for every official SDK — Node.js, Ruby, PHP, Python, Go, Rust, Java, .NET, the CLI — plus raw cURL, so your stack's tab is one click away.

## SMTP relay

If your framework or app speaks SMTP rather than HTTP, MailBlastr also offers an SMTP relay: authenticate with your `mb_` API key as the SMTP password and point your mailer at MailBlastr's SMTP host. This lets tools like WordPress, Django's email backend, or Nodemailer send through MailBlastr without any API code.

## Which should I use?

| You have… | Use |
| --- | --- |
| A Node.js / TypeScript project | Install the official `mailblastr` SDK. |
| A fresh project in another language | Call the REST API directly with your HTTP client. |
| A framework that only speaks SMTP | Use the SMTP relay with your API key as the password. |