# API Reference

> The SendDart REST API: base URL, authentication, content type, idempotency, rate limits, and error format.

The SendDart API is organized around REST. It has predictable, resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes and verbs.

## Base URL

```bash
https://www.senddart.com/api
```

All requests are made over HTTPS. The resources are mounted at the root: `/emails`, `/domains`, `/audiences`, `/campaigns`, `/api-keys`.

## Authentication

Authenticate with your API key as a Bearer token on every request. See [Authentication](https://www.senddart.com/docs/authentication).

```bash
Authorization: Bearer mb_xxxxxxxxx
```

## Official SDKs

Most endpoints in this reference show examples for the Node.js, Python, Ruby and PHP packages alongside raw cURL, plus a CLI tab wherever the CLI ships that command. The Go, Rust, Java and .NET tabs show the SDK for the core operations. Where an endpoint has no SDK mapping for a language, that tab falls back to an equivalent plain-HTTP request in the same language, so every sample is runnable as printed. Pick your language from the tabs on any request sample.

| Language | Package | Install |
| --- | --- | --- |
| Node.js | `senddart` | `npm install senddart` |
| Ruby | `senddart` | `gem install senddart` |
| PHP | `senddart/senddart` | `composer require senddart/senddart` |
| Python | `senddart` | `pip install senddart` |
| Go | `github.com/shekhu10/senddart-sdks/senddart-go` (package `senddart`) | `go get github.com/shekhu10/senddart-sdks/senddart-go` |
| Rust | `senddart` | `cargo add senddart` |
| Java | `com.senddart:senddart` | `implementation 'com.senddart:senddart:1.0.0'` |
| .NET | `SendDart` | `dotnet add package SendDart` |
| CLI | `senddart-cli` | `npm install -g senddart-cli` |

## Content type

Send request bodies as JSON with `Content-Type: application/json`. Responses are always JSON.

## User-Agent

All API requests must include a `User-Agent` header. Requests without it are rejected with a `403` status code. If you are making direct HTTP requests, set it explicitly:

```bash
User-Agent: my-app/1.0
```

> **Note:** If you get a `403` despite a valid API key, a missing `User-Agent` header is the likely cause.

## Response codes

SendDart uses standard HTTP codes: `2xx` for success, `4xx` for user-related failures, and `5xx` for infrastructure issues.

| Status | Description |
| --- | --- |
| `200` | Successful request. |
| `400` | Check that the parameters were correct. |
| `401` | The API key used was missing. |
| `402` | A plan limit was reached (for example the domain cap). Upgrade to continue. |
| `403` | The API key used was invalid. |
| `404` | The resource was not found. |
| `429` | The rate limit or an account quota was exceeded. |
| `5xx` | Indicates an error with SendDart servers. |

## Versioning

There is currently no versioning system in place. Versioning via calendar-based headers is planned for the future.

## Pagination

Some list endpoints support cursor-based pagination to browse large datasets efficiently.

## Idempotency

`POST /emails` and `POST /emails/batch` accept an optional `Idempotency-Key` header so a retried send is not processed twice. Other mutating endpoints ignore the header — a retry there creates a second resource. See [Idempotency keys](https://www.senddart.com/docs/emails/idempotency).

```bash
Idempotency-Key: <your-unique-key>
```

## Rate limits

The **send endpoints** (`POST /emails` and the transactional send API) are rate-limited per client IP to blunt bursts. When you exceed the send rate the response is a `429 rate_limit_exceeded` — read the `ratelimit-*` and `retry-after` headers and back off accordingly. Other endpoints are not subject to this per-request cap; sustained volume is governed by your account **quotas** instead (see [Usage limits](https://www.senddart.com/docs/api/limits)).

## Errors

Errors use standard HTTP status codes and a consistent JSON body. See the full [error reference](https://www.senddart.com/docs/api/errors).

```json
{
  "statusCode": 422,
  "name": "validation_error",
  "message": "`to` must contain between 1 and 50 recipients."
}
```