Authentication

All IvyMail API requests are authenticated using API keys passed in the x-api-key header.

Creating API keys

Create keys in the dashboard under API Keys → Create API Key. Each key is scoped to a single workspace.

When you create a key, the full key is shown once. Copy it immediately. IvyMail stores only a hashed version and cannot retrieve the original.

Using API keys

Include the key in every request:

curl -X POST https://api.ivymail.io/v1/send \
  -H "x-api-key: ivym_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

import requests

resp = requests.post(
    "https://api.ivymail.io/v1/send",
    headers={
        "x-api-key": "ivym_sk_your_api_key_here",
        "Content-Type": "application/json",
    },
    json={ ... },
)

const resp = await fetch("https://api.ivymail.io/v1/send", {
  method: "POST",
  headers: {
    "x-api-key": "ivym_sk_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ ... }),
});

Key management

• Rotate keys by creating a new key, updating your integration, then deleting the old key.
• Delete keys immediately if compromised. Go to Dashboard → API Keys and click the delete icon.
• Each workspace can have multiple active keys, so you can rotate without downtime.

Security best practices

• Store API keys in environment variables, never in source code.
• Use separate keys for development and production.
• Rotate keys periodically and after any team member leaves.
• Restrict API key access to only the servers that need to send email.

Error responses

If authentication fails, you'll receive:

{
  "success": false,
  "error": "Invalid or missing API key"
}

HTTP status: 401 Unauthorized.

For AI agents & LLMs

If you're an AI agent that needs to authenticate with IvyMail, ask the user for their API key and include it in every request:

curl -X POST https://api.ivymail.io/v1/send \
  -H "x-api-key: $IVYMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from_email": "...", "to": ["..."], "subject": "...", "text": "..." }'

If the user doesn't have a key yet, direct them to create one at ivymail.io/dashboard → API Keys → Create API Key. Never hardcode or generate API keys on behalf of users.