Get started

Using your API key

On this page

Base URL
Check that a key works
Errors
Keep the key out of your code
Next

Every request to the SimpleCold API sends your API key as a Bearer token in the Authorization header.

Header

Authorization: Bearer <your-api-key>

Replace <your-api-key> with the key you copied when you created it. There is no query-string key and no basic auth.

Base URL

https://simplecold.com/api/v1

Check that a key works

GET/api/v1/api-validation/validate

This endpoint does nothing except confirm your key. It takes no parameters and uses no credits, so it is a good first call and a useful startup check for long-running workers.

Request

curl "https://simplecold.com/api/v1/api-validation/validate" \
  -H "Authorization: Bearer $SIMPLECOLD_API_KEY"

const res = await fetch("https://simplecold.com/api/v1/api-validation/validate", {
  headers: { Authorization: `Bearer ${process.env.SIMPLECOLD_API_KEY}` },
});
const body = await res.json();

if (res.ok && body.payload.valid) {
  console.log("API key is valid");
} else {
  console.error(`Key check failed (${res.status}): ${body.message}`);
}

import os
import requests

res = requests.get(
    "https://simplecold.com/api/v1/api-validation/validate",
    headers={"Authorization": f"Bearer {os.environ['SIMPLECOLD_API_KEY']}"},
    timeout=10,
)
body = res.json()

if res.ok and body["payload"]["valid"]:
    print("API key is valid")
else:
    print(f"Key check failed ({res.status_code}): {body.get('message')}")

<?php
$ch = curl_init('https://simplecold.com/api/v1/api-validation/validate');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('SIMPLECOLD_API_KEY')],
    CURLOPT_TIMEOUT => 10,
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if ($status === 200 && $body['payload']['valid']) {
    echo "API key is valid\n";
} else {
    echo "Key check failed ($status): " . ($body['message'] ?? 'no response') . "\n";
}

Response · 200

{
  "code": "SUCCESS",
  "message": "Successfully performed operation.",
  "payload": {
    "valid": true,
    "message": "API key is valid"
  },
  "requestId": "3f1c..."
}

Errors

Authentication runs before anything else on every endpoint. A problem with the key returns 401 with this body:

Response · 401

{
  "code": "FAILURE",
  "message": "Invalid API key",
  "data": null
}

Message	Cause
`Authorization header is required`	The header is missing.
`Authorization header must be in format: Bearer <token>`	The header is malformed, for example missing `Bearer` or with an extra space.
`API key is required`	`Bearer` with no key after it.
`Invalid API key`	No such key. Often a copy-paste error or a key that was regenerated.
`API key is inactive`	The key is disabled in the dashboard.
`API key has expired`	The key passed its expiry date. Update its expiry or create a new key.

None of these fix themselves, so don't retry a 401. Fail fast and alert someone.

Keep the key out of your code

.env

SIMPLECOLD_API_KEY=your-api-key

Node.js

const apiKey = process.env.SIMPLECOLD_API_KEY;

import os
api_key = os.environ["SIMPLECOLD_API_KEY"]

$apiKey = getenv('SIMPLECOLD_API_KEY');

Call the API from your server only. A key in browser or mobile code can be read by anyone.

Single validation
Test emails: try every result without using credits.

Base URL

Check that a key works

Errors

Keep the key out of your code

Next