# API Reference

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

The SendPing 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.sendping.co/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.sendping.co/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 | `sendping` | `npm install sendping` |
| Ruby | `sendping` | `gem install sendping` |
| PHP | `sendping/sendping` | `composer require sendping/sendping` |
| Python | `sendping` | `pip install sendping` |
| Go | `github.com/shekhu10/sendping-sdks/sendping-go` (package `sendping`) | `go get github.com/shekhu10/sendping-sdks/sendping-go` |
| Rust | `sendping` | `cargo add sendping` |
| Java | `co.sendping:sendping` | `implementation 'co.sendping:sendping:5.1.1'` |
| .NET | `SendPing` | `dotnet add package SendPing` |
| CLI | `sendping-cli` | `npm install -g sendping-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

SendPing 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 SendPing 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.sendping.co/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.sendping.co/docs/api/limits)).

## Errors

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

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