API Keys

Note

The RelayPost dashboard uses a separate internal GraphQL API. This documentation covers the public REST API for external integrations.

API keys authenticate your application when calling the RelayPost REST API. Each key is scoped to an organization — it can only access that organization’s data.

Key format

API keys follow this format:

rp_live_aBcDeFgHiJkLmNoPqRsT...

Prefix	Meaning
rp_live_	Production key
rp_test_	Test/sandbox key

Only the first 12 characters (the prefix) are stored for display. The full key is shown once at creation time and cannot be retrieved later.

Create and manage API keys

API keys are created and managed through the RelayPost dashboard under Settings → API Keys. From there you can:

• Create new keys with a name and environment (production or test)
• View existing keys (prefix only — the full key is shown once at creation)
• Revoke keys that are no longer needed

Caution

Copy the full API key immediately when it’s created — it’s only shown once and cannot be retrieved later.

Revoked keys immediately stop working. This cannot be undone — create a new key if needed.

Using your API key

Include the key in the Authorization header on all REST API requests:

cURL

curl -X POST https://relaypost.dev/api/v1/emails/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rp_live_aBcDeFgHiJkLmNoPqRsT..." \
  -d '{
    "from": { "email": "[email protected]", "name": "Your App" },
    "to": [{ "email": "[email protected]" }],
    "subject": "Hello from RelayPost",
    "html": "<p>It works!</p>"
  }'

JavaScript

const response = await fetch("https://relaypost.dev/api/v1/emails/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer rp_live_aBcDeFgHiJkLmNoPqRsT...",
  },
  body: JSON.stringify({
    from: { email: "[email protected]", name: "Your App" },
    to: [{ email: "[email protected]" }],
    subject: "Hello from RelayPost",
    html: "<p>It works!</p>",
  }),
});

const result = await response.json();
console.log(result.data.message_id);

Python

import requests

response = requests.post(
    "https://relaypost.dev/api/v1/emails/send",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer rp_live_aBcDeFgHiJkLmNoPqRsT...",
    },
    json={
        "from": {"email": "[email protected]", "name": "Your App"},
        "to": [{"email": "[email protected]"}],
        "subject": "Hello from RelayPost",
        "html": "<p>It works!</p>",
    },
)

result = response.json()
print(result["data"]["message_id"])

Authentication errors

If the API key is missing or invalid, the API returns a JSON error:

{
  "error": {
    "code": "AUTH_MISSING",
    "message": "No Authorization header provided"
  }
}

{
  "error": {
    "code": "AUTH_INVALID",
    "message": "API key is invalid or revoked"
  }
}

Rate limit headers

Every REST API response includes rate limit information in the headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window
Retry-After	Seconds to wait before retrying (only on 429 responses)

See Rate Limits for details.

Security best practices

• Never commit API keys to version control
• Use environment variables to store keys
• Use test environment keys during development
• Rotate keys periodically — revoke old ones and create new ones
• Use separate keys for different services so you can revoke individually