> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate turboSMTP API Requests

> Use Consumer Key and Secret headers for sending and management, understand permissions, and identify endpoints that require a session API key.

Use a **Consumer Key / Secret** pair for your turboSMTP integration. The same pair can authenticate SMTP, HTTP sending, and management requests when you enable the corresponding permissions.

## Create credentials

Open **Settings → Integrations → API Keys → Edit** in the [dashboard](https://dashboard.serversmtp.com) and create a key. Store the Consumer Secret securely when it is shown. You cannot retrieve it later.

| Dashboard permission | API value | Access |
| - | - | - |
| SMTP Sending | `SEND_SMTP` | Authenticate with the SMTP relay |
| HTTP API Sending | `SEND_API` | Call `POST /mail/send` |
| Statistics & Management APIs | `APIS` | Analytics, suppressions, validation, alerts, and sub-account management |

Enable only the permissions your application needs. If you restrict the key to IP addresses, include the public outgoing IP of your application server. See [API keys](/docs/get-started/api-keys.md).

## Authenticate API requests

Pass both headers on each request. Management endpoints use `https://pro.api.serversmtp.com/api/v2`:

```bash Read account information theme={"system"}
curl 'https://pro.api.serversmtp.com/api/v2/user/info' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET'
```

Sending uses a separate host:

```bash Send an email theme={"system"}
curl 'https://api.turbo-smtp.com/api/v2/mail/send' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"from":"sender@example.com","to":"recipient@example.com","subject":"Hello","content":"Hello from turboSMTP."}'
```

For EU sending, use `https://api.eu.turbo-smtp.com/api/v2/mail/send`. The request format is identical.

> [!NOTE]
>
> `/mail/send` authenticates only with `consumerKey` and `consumerSecret`. An `Authorization` header is ignored. It does not replace either Consumer header, and a request carrying only `Authorization` fails authentication.

## SMTP authentication

Use the **Consumer Key as the username** and the **Consumer Secret as the password** on `pro.turbo-smtp.com` or `pro.eu.turbo-smtp.com`. Enable **SMTP Sending** on the key. Use [SMTP setup](/docs/get-started/smtp-configuration.md) for ports and encryption settings.

Older accounts may have a legacy Consumer Key whose value equals the account email. Use it as a Consumer Key with its associated secret. This does not mean your dashboard email and password are SMTP credentials. New sub-accounts need their own key pair.

## Endpoints that require a session API key

Consumer credentials are not accepted by `/user/consumerKeys` and its key-specific operations, `/change-password`, or `/update-password`. These require a session API key in the raw `Authorization` header:

```http Session authentication theme={"system"}
Authorization: YOUR_SESSION_API_KEY
```

Do not add a `Bearer` prefix. Use the dashboard for key management and password changes when you do not have a working session API key.

### Legacy login: POST /authorize

> [!NOTE]
>
> `/authorize` checks the same email and password you use for the dashboard. The account must have signed in to the dashboard at least once; otherwise the endpoint returns `wrong_credentials_specified`. Use Consumer Key / Secret for integrations and reserve this login for the session-only operations below.

The legacy endpoint accepts `email`, `password`, and optional `no_expire`. When login produces a usable token, it is returned as `auth`. Session keys expire after two hours of inactivity by default; this is an idle timeout, not a fixed lifetime. `no_expire: true` requests a non-expiring key. An HTTP `200` alone does not establish that the returned token will authenticate later requests.

`/authorize` permits 10 calls per IP within two minutes, including failed attempts. Exceeding the limit can block that IP until support clears it; subsequent calls return `401` with `api_limit_reached`. Do not use repeated login attempts as a health check. The same per-IP limit applies to the forgot-password endpoints.

### Revoke a session key

```bash Revoke the current session API key theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/deauthorize' \
  -H 'Authorization: YOUR_SESSION_API_KEY'
```

```json Response theme={"system"}
{"message":"token_deauthorized"}
```

To revoke a Consumer Key, delete it from **Settings → Integrations → API Keys → Edit** or use the [Consumer Keys API](/docs/api-reference/consumer-keys.md).

### Change a password

`PUT /change-password` requires a session API key and these fields:

```json Request body theme={"system"}
{
  "current_password": "CURRENT_PASSWORD",
  "password": "NEW_PASSWORD",
  "confirm_password": "NEW_PASSWORD"
}
```

The new password must contain at least 10 characters, including an uppercase letter, a lowercase letter, and a number. The two new-password fields must match. Prefer the dashboard's account-security settings for routine password changes.

## Password recovery

Use the **Forgot password** link on the dashboard sign-in screen to recover dashboard access. The legacy API also exposes these operations on the management host:

| Operation | Input |
| - | - |
| `POST /forgot-password` | JSON body containing `email` |
| `GET /forgot-password` | Query parameter `token`; the API specification also requires session authentication |
| `PUT /forgot-password` | JSON body containing `token`, `password`, and `confirm_password` |

Recovery tokens are valid for one hour. A successful recovery-request response does not reveal whether the email is registered. These legacy API operations do not remove the `/authorize` compatibility limitation described above.

## Credential handling

Keep secrets on the server, outside source control and browser code. Rotate a Consumer Key by creating a replacement, updating your applications, checking authentication, and then deleting the old key. Treat session API keys as secrets too.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.