Maildesk API Authentication Guide

This guide walks you through authenticating to the Maildesk public API, specifically the Subscribers (/api/subscribers) and Tags (/api/tags) endpoints.

1. Overview

Maildesk's public API uses Bearer token authentication backed by a per-business secret API key. Both the Subscribers and Tags controllers are protected by the same two guards

2. Obtaining Your API Key

API keys are provisioned automatically when a business account is created. You can view and copy them from the dashboard:

Navigate to Settings → API Keys (/settings/api-keys).

You'll see two values:

Public key — prefixed with pk_ (used for client-side identification; not used for API auth).

Secret key — prefixed with sk_ (this is what you use to authenticate API requests).

Keep the secret key private. It grants full read/write access to the subscribers and tags of your business.

3. Authenticating a Request

Include your secret key in the Authorization HTTP header using the Bearer scheme on every API request:

How it's validated

On every request:

The token is extracted from the Authorization header and validated

If not found, the server responds with 401 Unauthorized.

4. Example Requests

Create a Subscriber

5. Rate Limiting

Requests are throttled per bearer token (not per IP), so each API key gets its own bucket.

Limit: 120 requests per 60 seconds

When you exceed the limit, the server responds with 429 Too Many Requests. Back off and retry after the window resets.

6. Error Responses

Status	Meaning
401	Missing, malformed, or invalid bearer token (Unauthorized request)
404	Resource not found or does not belong to the authenticated business
429	Rate limit exceeded for this token

API Authentication

Maildesk API Authentication Guide#

1. Overview#

2. Obtaining Your API Key#

3. Authenticating a Request#

How it's validated#

4. Example Requests#

Create a Subscriber#

5. Rate Limiting#

6. Error Responses#