# Quickstart

> Send your first email with the MailBlastr API in a few minutes.

## Prerequisites

1. A **verified domain** — add one under Domains and publish its DNS records. ([guide](https://www.mailblastr.com/docs/domains/managing))
2. An **API key** — create one under API Keys. It starts with `mb_` and is shown once. ([guide](https://www.mailblastr.com/docs/authentication))

## Install the SDK

Using Node.js? Install the official [`mailblastr`](https://www.mailblastr.com/docs/resources/sdks) SDK — the Node.js examples throughout these docs use it. From any other language, call the REST API directly (see the cURL / Python / other tabs in each example).

```sh
npm install mailblastr
```

## Send an email

Replace `mb_xxxxxxxxx` with your API key and use a `from` address on your verified domain.

**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": ["delivered@example.com"],
  "subject": "Hello from MailBlastr",
  "html": "<p>Your first email 🎉</p>"
});
console.log({ data, error });
```

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": [
    "delivered@example.com"
  ],
  "subject": "Hello from MailBlastr",
  "html": "<p>Your first email 🎉</p>"
})
```

**PHP**

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

$mailblastr->emails->send([
  'from' => "Acme <hello@yourdomain.com>",
  'to' => [
    "delivered@example.com"
  ],
  'subject' => "Hello from MailBlastr",
  'html' => "<p>Your first email 🎉</p>"
]);
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": [
    "delivered@example.com"
  ],
  "subject": "Hello from MailBlastr",
  "html": "<p>Your first email 🎉</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": ["delivered@example.com"],
  "subject": "Hello from MailBlastr",
  "html": "<p>Your first email 🎉</p>"
}'
```

**CLI**

```bash
mailblastr emails send \
  --from 'Acme <hello@yourdomain.com>' \
  --to 'delivered@example.com' \
  --subject 'Hello from MailBlastr' \
  --html '<p>Your first email 🎉</p>'
```

## Response

A successful send returns the email `id` you can use to [retrieve the email](https://www.mailblastr.com/docs/api/emails-get) or correlate webhook events.

```json
{
  "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
}
```

> **Warning:** If you get `validation_error` about the domain not being verified, finish the DNS verification first — emails can only be sent from a verified domain you own (or a subdomain of one).

## Test addresses

To simulate delivery events without sending to a real inbox (and without damaging your domain reputation), send to one of these reserved test recipients:

| Address | Simulates |
| --- | --- |
| `delivered@example.com` | A successful delivery. |
| `bounced@example.com` | A hard bounce. |
| `complained@example.com` | A spam complaint. |
| `suppressed@example.com` | A recipient on the suppression list. |

## Avoid duplicates with an idempotency key

To safely retry a send without delivering the same email twice, pass an `Idempotency-Key` header. A repeated request with the same key within the window returns the original result instead of sending again.

- Must be **unique per logical request**.
- Keys expire after **24 hours**.
- Maximum length **256 characters**.
- Recommended pattern: `<event-type>/<entity-id>` — for example `welcome-user/123456789`.

```bash
curl -X POST 'https://api.mailblastr.com/emails' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: welcome-user/123456789' \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["delivered@example.com"],
    "subject": "Hello from MailBlastr",
    "html": "<p>Your first email 🎉</p>"
  }'
```

## Next steps

- [Schedule an email](https://www.mailblastr.com/docs/emails/schedule) for later delivery.
- [Add attachments](https://www.mailblastr.com/docs/emails/attachments) or [custom headers](https://www.mailblastr.com/docs/emails/headers).
- [Send a batch](https://www.mailblastr.com/docs/emails/batch) of up to 100 emails in one request.
- [Receive webhooks](https://www.mailblastr.com/docs/webhooks/overview) for delivery and engagement events.