> For the complete documentation index, see [llms.txt](https://docs.sendman.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sendman.com/other/rest-api.md).

# REST API

The Sendman REST API is available under https\://YOURNAME.sendman.com/sendman/v1

Sendman exposes a REST API that allows you to automate the configuration you would otherwise perform in the Sendman Admin Portal, e.g. provisioning SMTP credentials and policies for new devices.

{% hint style="warning" %}
Before executing any API call that leads to a configuration change, ensure you fully understand the implications. Incorrect use of the API may break the mail flow of your instance.
{% endhint %}

## Authentication

To authenticate a call to the REST API, add an HTTP `Authorization` header to each request. This header must contain a valid [access token](/admin-portal/settings/permissions.md#api-access-tokens):

```
Authorization: Bearer <Access Token>
```

Tokens with the role **Administrator** can read and change the configuration. Tokens with the role **Viewer** can only read it.

## Base URL

```
https://YOURNAME.sendman.com/sendman/v1
```

## Endpoints

| Resource                   | Endpoint                               | Methods                        |
| -------------------------- | -------------------------------------- | ------------------------------ |
| IP allow list              | `/global-ip-allow-list`                | `GET`, `POST`                  |
|                            | `/global-ip-allow-list/{id}`           | `PUT`, `DELETE`                |
| Authorization policies     | `/authorization-policies`              | `GET`, `POST`                  |
|                            | `/authorization-policies/{id}`         | `PUT`, `DELETE`                |
| SMTP credentials           | `/credentials`                         | `GET`, `POST`                  |
|                            | `/credentials/{id}`                    | `PUT`, `DELETE`                |
| Settings                   | `/settings/{name}`                     | `GET`, `HEAD`, `PUT`, `DELETE` |
| Backend client certificate | `/settings/backend-client-certificate` | `GET`, `PUT`, `DELETE`         |
| Version                    | `/versions/current`                    | `GET`                          |

### Conventions

* Request and response bodies are JSON.
* Lists are returned in a `values` array: `{ "values": [ ... ] }`.
* IPv4 addresses are passed as **signed 32-bit integers** in network byte order, e.g. `192.0.2.10` becomes `-1073741302` (fields `startIpAsInt` and `endIpAsInt`).
* Validation errors are returned as `400 Bad Request` with a [problem details](https://www.rfc-editor.org/rfc/rfc9457) body.
* Passwords, the backend password and the client certificate are never returned.

### Settings

The `/settings/{name}` endpoint reads and writes the following settings of the [SMTP Backend](/admin-portal/settings/smtp-backend.md) and [SMTP Client](/admin-portal/settings/smtp-client.md) pages. The body of a `PUT` request is `{ "value": "..." }`.

| Name                                                   | Portal field                                                        |
| ------------------------------------------------------ | ------------------------------------------------------------------- |
| `SmtpRelaySettings--BackendServer`                     | Server address                                                      |
| `SmtpRelaySettings--BackendPort`                       | Port                                                                |
| `SmtpRelaySettings--BackendUsername`                   | Username                                                            |
| `SmtpRelaySettings--BackendPassword`                   | Password (write-only)                                               |
| `SmtpRelaySettings--EnableBackendAuthentication`       | Authenticate at the backend with these credentials (`true`/`false`) |
| `SmtpRelaySettings--EnableMutualTlsToBackend`          | Use the client certificate for mutual TLS (`true`/`false`)          |
| `SmtpRelaySettings--EnableLegacyClientTlsCipherSuites` | Allow legacy TLS cipher suites (`true`/`false`)                     |

## Examples

### Create an SMTP credential

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://YOURNAME.sendman.com/sendman/v1/credentials" \
  -H "Authorization: Bearer $SENDMAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "scanner-hq", "password": "<password>", "description": "Scanner headquarters"}'
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
$headers = @{ Authorization = "Bearer $env:SENDMAN_TOKEN" }
$body = @{
    username    = "scanner-hq"
    password    = "<password>"
    description = "Scanner headquarters"
} | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "https://YOURNAME.sendman.com/sendman/v1/credentials" `
    -Headers $headers -ContentType "application/json" -Body $body
```

{% endtab %}
{% endtabs %}

### Create an authorization policy for the credential

```bash
curl -X POST "https://YOURNAME.sendman.com/sendman/v1/authorization-policies" \
  -H "Authorization: Bearer $SENDMAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "priority": 100,
        "identityProvider": "Sendman",
        "username": "scanner-hq",
        "allowedSenders": ["scanner@contoso.com"],
        "allowedReceivers": [".*@contoso\\.com"],
        "allowAnonymous": false,
        "description": "Scanner headquarters"
      }'
```

### Add address ranges to the allow list

The `POST` request accepts several entries at once. Entries that overlap existing entries are skipped and reported in the response with status `409 Conflict`.

```bash
curl -X POST "https://YOURNAME.sendman.com/sendman/v1/global-ip-allow-list" \
  -H "Authorization: Bearer $SENDMAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entries": [{"startIpAsInt": -1073741312, "endIpAsInt": -1073741057, "description": "192.0.2.0/24"}]}'
```

### List all policies

```bash
curl "https://YOURNAME.sendman.com/sendman/v1/authorization-policies" \
  -H "Authorization: Bearer $SENDMAN_TOKEN"
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sendman.com/other/rest-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.