Authentication

Every API request is authenticated with a Bearer API key. Three steps to your first authenticated call.

Get a key

Create one in Dashboard → API Keys. Keys start with cmd_ and are shown in full exactly once — see the API Keys guide.

Send it as a Bearer token

Pass the key in the Authorization header on every request. The SDK does this for you.

cURL

curl https://api.cmdsend.com/v1/emails \
  -H "Authorization: Bearer $CMDSEND_API_KEY"

Node.js

import { Cmdsend } from 'cmdsend';

// The key is sent on every request — server-side only, never in the browser.
const cmdsend = new Cmdsend(process.env.CMDSEND_API_KEY);

Confirm it works

List your emails. A 200 means the key is good — even with no sends yet, you get an empty list rather than an error.

curl -s "https://api.cmdsend.com/v1/emails?per_page=1" \
  -H "Authorization: Bearer $CMDSEND_API_KEY"

# {"data":[],"pagination":{"page":1,"per_page":1,"total":0,"total_pages":0}}

Permissions

Each key is scoped at creation. A request to an endpoint outside its scope is rejected even though the key itself is valid.

Permission	Grants
emails:send	Send email via POST /v1/emails/send
emails:read	Read email status, events, and attachment metadata

When auth fails

Error	Cause
`Unauthorized` 401	The header is missing or malformed, or the key was revoked. Check for a stray newline in the environment variable.
`Forbidden` 403	The key is valid but lacks the permission for this endpoint, the from domain is not verified, or the account is suspended.

Keeping keys safe

Server-side only. A key in client-side code is a key anyone can read and send from.
One key per environment, so revoking staging never touches production.
Deleting a key revokes it immediately — roll out the replacement first. See rotating a key.