> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senderr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Learn how to integrate with Senderr's powerful email template API

# Senderr API Reference

Welcome to the Senderr API! Our RESTful API enables you to programmatically access your email template library, render templates with custom variables, and send emails using your purchased or created templates.

## Base URL

All API requests should be made to:

```
https://senderr.dev/api/v1
```

For development and testing:

```
http://localhost:3000/api/v1
```

## Authentication

Senderr API supports two authentication methods:

### 1. API Key Authentication (Recommended for server-side)

Include your API key in the request header:

```bash theme={null}
curl -H "X-API-Key: your-api-key-here" \
     https://senderr.dev/api/v1/library
```

Or using the Authorization header:

```bash theme={null}
curl -H "Authorization: Bearer your-api-key-here" \
     https://senderr.dev/api/v1/library
```

### 2. Session Authentication (Browser-based)

When making requests from a logged-in browser session, authentication is handled automatically via secure HTTP-only cookies.

## Getting Your API Key

1. Log in to your [Senderr Dashboard](https://senderr.dev/dashboard)
2. Navigate to Settings → API Keys
3. Click "Generate New API Key"
4. Copy and securely store your key

<Warning>
  API keys provide full access to your account. Keep them secure and never expose them in client-side code.
</Warning>

## Rate Limits

API usage is limited based on your subscription plan:

| Plan        | Monthly API Calls | Email Sending       |
| ----------- | ----------------- | ------------------- |
| **Free**    | 500 calls/month   | 100 emails/month    |
| **Monthly** | Unlimited         | 10,000 emails/month |
| **Annual**  | Unlimited         | 50,000 emails/month |

Rate limit information is included in response headers:

```
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 450
X-RateLimit-Reset: 2024-02-01T00:00:00Z
X-RateLimit-Plan: free
```

## Error Handling

The API uses conventional HTTP response codes and returns JSON error responses:

```json theme={null}
{
  "error": "Template not found",
  "message": "This template is not in your library",
  "success": false,
  "code": "TEMPLATE_NOT_FOUND"
}
```

### Common HTTP Status Codes

| Code  | Description                                        |
| ----- | -------------------------------------------------- |
| `200` | Success                                            |
| `400` | Bad Request - Invalid parameters                   |
| `401` | Unauthorized - Invalid or missing API key          |
| `403` | Forbidden - Access denied (template not purchased) |
| `404` | Not Found - Resource doesn't exist                 |
| `429` | Too Many Requests - Rate limit exceeded            |
| `500` | Internal Server Error                              |

## Pagination

List endpoints support pagination using `limit` and `offset` parameters:

```bash theme={null}
curl "https://senderr.dev/api/v1/library?limit=20&offset=40" \
     -H "X-API-Key: your-api-key"
```

## SDKs and Libraries

Official SDKs are coming soon. For now, you can use any HTTP client library in your preferred programming language.

### Quick Start Examples

<CodeGroup>
  ```javascript JavaScript/Node.js theme={null}
  const senderr = {
    apiKey: 'your-api-key',
    baseUrl: 'https://senderr.dev/api/v1',

    async request(endpoint, options = {}) {
      const response = await fetch(`${this.baseUrl}${endpoint}`, {
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': this.apiKey,
          ...options.headers
        },
        ...options
      });
      return response.json();
    },

    // Get your template library
    async getLibrary() {
      return this.request('/library');
    },

    // Send an email
    async sendEmail(templateId, to, subject, variables) {
      return this.request('/send', {
        method: 'POST',
        body: JSON.stringify({
          template_id: templateId,
          to,
          subject,
          variables
        })
      });
    }
  };

  // Usage
  const library = await senderr.getLibrary();
  console.log(`You have ${library.templates.length} templates`);
  ```

  ```python Python theme={null}
  import requests

  class Senderr:
      def __init__(self, api_key):
          self.api_key = api_key
          self.base_url = 'https://senderr.dev/api/v1'
          self.headers = {
              'Content-Type': 'application/json',
              'X-API-Key': api_key
          }

      def request(self, endpoint, method='GET', data=None):
          url = f"{self.base_url}{endpoint}"
          response = requests.request(
              method, url,
              headers=self.headers,
              json=data
          )
          return response.json()

      def get_library(self):
          return self.request('/library')

      def send_email(self, template_id, to, subject, variables):
          return self.request('/send', 'POST', {
              'template_id': template_id,
              'to': to,
              'subject': subject,
              'variables': variables
          })

  # Usage
  senderr = Senderr('your-api-key')
  library = senderr.get_library()
  print(f"You have {len(library['templates'])} templates")
  ```

  ```bash cURL theme={null}
  # Get your template library
  curl -H "X-API-Key: your-api-key" \
       https://senderr.dev/api/v1/library

  # Send an email using a template
  curl -X POST https://senderr.dev/api/v1/send \
       -H "Content-Type: application/json" \
       -H "X-API-Key: your-api-key" \
       -d '{
         "template_id": "550e8400-e29b-41d4-a716-446655440000",
         "to": ["recipient@example.com"],
         "subject": "Welcome!",
         "variables": {
           "name": "John Doe"
         }
       }'
  ```
</CodeGroup>

## Next Steps

* Browse your [Template Library](/api-reference/library) to see what templates you have access to
* Learn how to [Render Templates](/api-reference/templates) with custom variables
* Start [Sending Emails](/api-reference/send) programmatically
* Check your [API Usage](/api-reference/usage) and limits

## Support

Need help with the API? Contact our support team:

* 📧 [support@senderr.dev](mailto:support@senderr.dev)
* 📚 [Community Discord](https://senderr.dev/community)
* 🐛 [Report Issues](https://github.com/senderr-dev/issues)