# Send emails over raw HTTP / cURL

> The canonical POST /emails request — headers, body, and response — that any HTTP client can reproduce.

At its core, MailBlastr is a plain JSON REST API — every SDK and framework guide is a wrapper around the same HTTP request shown here. If your language or tool can make an HTTPS `POST` with a couple of headers and a JSON body, it can send email through MailBlastr. Node.js / TypeScript users can skip the raw HTTP call and `npm install mailblastr` instead.

This is the canonical request. Reproduce it in `curl`, Postman, an HTTP client library, or a no-code tool.

## Prerequisites

1. A **verified domain** so your `from` address is allowed. ([guide](https://www.mailblastr.com/docs/domains/managing))
2. An **API key** (`mb_...`) for the `Authorization` header. ([Authentication](https://www.mailblastr.com/docs/authentication))

`POST /emails`

## Request headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Your API key as a Bearer token: `Bearer mb_xxxxxxxxx`. See [Authentication](https://www.mailblastr.com/docs/authentication). |
| `Content-Type` | string | Yes | Must be `application/json` — the body is a JSON object. |
| `Idempotency-Key` | string | No | Optional. A unique key so a retried request sends only once. See [Idempotency keys](https://www.mailblastr.com/docs/emails/idempotency). |

## The canonical request

Replace `mb_xxxxxxxxx` with your key and use a `from` address on your verified domain. The minimum body is `from`, `to`, `subject`, and one of `html` / `text`.

```bash
curl -X POST 'https://www.mailblastr.com/api/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>Sent over raw HTTP.</p>"
  }'
```

> **Note:** Any HTTP client works — `curl`, `wget`, `HTTPie`, Postman, Insomnia, or your language's native client. The full set of body fields (`cc`, `bcc`, `reply_to`, `headers`, `attachments`, `tags`, `scheduled_at`) is documented in the [Send Email API](https://www.mailblastr.com/docs/api/emails-send) reference.

## Handling the response

A successful send returns HTTP `200` with the new email `id`:

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

On failure the status is non-2xx and the body is a `{ statusCode, name, message }` error object. Always branch on the HTTP status before reading the `id`.

```json
{
  "statusCode": 422,
  "name": "validation_error",
  "message": "The domain yourdomain.com is not verified."
}
```

> **Warning:** Send this request only from a **server** (or a private script). The `mb_` API key authenticates as your account — never put it in a browser, a mobile app, or any client a user can inspect. Load it from an environment variable, not a literal in your code.

## Next steps

- See the full [Send Email API](https://www.mailblastr.com/docs/api/emails-send) reference for every header, body field, and error.
- Walk through the [Quickstart](https://www.mailblastr.com/docs/quickstart) end to end.
- Read [Authentication](https://www.mailblastr.com/docs/authentication) to understand key permissions.