Authentication

API Keys

All API requests require authentication using an API key. API keys are tied to your account and have access to all your templates and projects.

Creating an API Key

1. Go to Settings in your dashboard
2. Navigate to API Keys
3. Click Create API Key
4. Give it a descriptive name (e.g., “Production Server”)
5. Copy the key immediately—it won’t be shown again

Using Your API Key

Include the API key in the Authorization header of every request:

curl -X POST https://api.mailsh.it/v1/render \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "..."}'

Security Best Practices

Keep Keys Secret

• Never commit API keys to version control
• Use environment variables to store keys
• Don’t expose keys in client-side code

Use Environment Variables

# .env file
MAILSHIT_API_KEY=your_api_key_here

// In your code
const apiKey = process.env.MAILSHIT_API_KEY

Rotate Keys Regularly

If you suspect a key has been compromised:

1. Create a new API key
2. Update your application to use the new key
3. Delete the compromised key

Use Separate Keys for Environments

Create different API keys for:

• Development
• Staging
• Production

This makes it easier to revoke access if needed and track usage.

Revoking API Keys

To revoke an API key:

1. Go to Settings > API Keys
2. Find the key you want to revoke
3. Click Delete

The key will stop working immediately. Any requests using that key will receive a 401 Unauthorized response.

Error Responses

Missing API Key

{
  "error": "Authorization header is required"
}

Status: 401 Unauthorized

Invalid API Key

{
  "error": "Invalid API key"
}

Status: 401 Unauthorized

Expired/Revoked Key

{
  "error": "API key has been revoked"
}

Status: 401 Unauthorized