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

# API Introduction

> Integrate MailGreet into your applications with our powerful REST API

## Welcome to the MailGreet API

The MailGreet API provides programmatic access to your email marketing platform, enabling you to automate subscriber management, trigger campaigns, and integrate with your existing tools seamlessly.

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="#quick-start">
    Get up and running in 5 minutes
  </Card>

  <Card title="Authentication" icon="key" href="#authentication">
    Learn how to authenticate your requests
  </Card>

  <Card title="Subscribers API" icon="users" href="/api-reference/subscribers/list">
    Manage your subscriber list
  </Card>

  <Card title="Postman Collection" icon="vial" href="#postman-collection">
    Download and test the API
  </Card>
</CardGroup>

***

## Base URL

All API requests should be made to the following base URL:

```bash Production theme={null}
https://api.mailgreet.com/api/v1/external
```

***

## Authentication

<Note>
  All API endpoints (except public endpoints like Health Check and Plans) require authentication using a Bearer token.
</Note>

### Getting Your API Key

1. Log in to your [MailGreet Dashboard](https://mailgreet.com/dashboard)
2. Navigate to **Settings** → **Integrations**
3. Click **"Generate New API Key"**
4. Copy and securely store your API key

<Warning>
  Your API key grants full access to your account. Keep it secure and never expose it in client-side code or public repositories.
</Warning>

### Using Your API Key

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

```bash theme={null}
curl -X GET "https://api.mailgreet.com/api/v1/external/subscribers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Test Your Authentication

Before making other requests, verify your API key is working:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.mailgreet.com/api/v1/external/test-auth" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.mailgreet.com/api/v1/external/test-auth', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

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

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

  headers = {
      'Authorization': 'Bearer YOUR_API_KEY'
  }

  response = requests.get(
      'https://api.mailgreet.com/api/v1/external/test-auth',
      headers=headers
  )

  print(response.json())
  ```

  ```php PHP theme={null}
  $ch = curl_init();

  curl_setopt_array($ch, [
      CURLOPT_URL => 'https://api.mailgreet.com/api/v1/external/test-auth',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer YOUR_API_KEY'
      ]
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  echo $response;
  ```
</CodeGroup>

**Successful Response:**

```json theme={null}
{
  "success": true,
  "message": "API key authentication successful",
  "data": {
    "user_id": "uuid-here",
    "clerk_user_id": "user_xxxxx",
    "api_key_name": "Default API Key",
    "authenticated_at": "2026-01-18T14:00:00Z"
  }
}
```

***

## Quick Start

Get started with the MailGreet API in just a few steps:

<Steps>
  <Step title="Get Your API Key">
    Generate your API key from the Integrations page in your dashboard.
  </Step>

  <Step title="Test Authentication">
    Verify your API key works by calling the `/test-auth` endpoint.
  </Step>

  <Step title="Create Your First Subscriber">
    Add a subscriber using the Subscribers API.
  </Step>

  <Step title="Start Building">
    Explore the full API to build powerful integrations.
  </Step>
</Steps>

### Your First API Call

Here's how to create a subscriber:

```bash theme={null}
curl -X POST "https://api.mailgreet.com/api/v1/external/subscribers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }'
```

***

## Response Format

All API responses follow a consistent JSON structure:

### Success Response

```json theme={null}
{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Optional success message"
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": "Description of what went wrong",
  "data": {
    // Optional additional error details
  }
}
```

***

## HTTP Status Codes

| Status Code | Description                                                      |
| ----------- | ---------------------------------------------------------------- |
| `200`       | Success - Request completed successfully                         |
| `201`       | Created - Resource created successfully                          |
| `400`       | Bad Request - Invalid request parameters                         |
| `401`       | Unauthorized - Invalid or missing API key                        |
| `403`       | Forbidden - API key lacks required permissions or limit exceeded |
| `404`       | Not Found - Resource doesn't exist                               |
| `422`       | Unprocessable Entity - Validation error                          |
| `429`       | Too Many Requests - Rate limit exceeded                          |
| `500`       | Internal Server Error - Something went wrong on our end          |

***

## Rate Limiting

To ensure fair usage and maintain API stability, requests are rate-limited based on your plan:

| Plan       | Rate Limit          |
| ---------- | ------------------- |
| Free       | 60 requests/minute  |
| Starter    | 300 requests/minute |
| Pro        | 600 requests/minute |
| Enterprise | Custom              |

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response with a `Retry-After` header indicating when you can retry.

<Tip>
  Implement exponential backoff in your applications to handle rate limiting gracefully.
</Tip>

***

## Pagination

List endpoints support pagination with the following query parameters:

| Parameter  | Type    | Default | Description               |
| ---------- | ------- | ------- | ------------------------- |
| `page`     | integer | 1       | Page number               |
| `per_page` | integer | 20      | Items per page (max: 100) |

**Paginated Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "subscribers": [...],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_count": 100,
      "per_page": 20
    }
  }
}
```

***

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield-check" href="/api-reference/endpoint/authentication">
    Test API key authentication
  </Card>

  <Card title="Subscribers" icon="users" href="/api-reference/endpoint/subscribers">
    Create, read, update, delete subscribers
  </Card>

  <Card title="Health Check" icon="heart-pulse" href="/api-reference/endpoint/health">
    Check API availability (no auth required)
  </Card>

  <Card title="Plans" icon="credit-card" href="/api-reference/endpoint/plans">
    View available subscription plans
  </Card>
</CardGroup>

***

## Postman Collection

We provide a complete Postman collection for testing all API endpoints.

<Card title="Download Postman Collection" icon="download" href="https://github.com/mailgreet/docs/blob/main/api-reference/MailGreet_API_Collection.postman_collection.json">
  Import into Postman and start testing immediately
</Card>

### Setup Instructions

1. **Import the Collection**: Download the JSON file and import it into Postman
2. **Set Variables**: Configure the following collection variables:
   * `base_url`: Your API base URL
   * `api_key`: Your MailGreet API key
3. **Start Testing**: Run any request to test the API

***

## SDKs & Libraries

<Info>
  Official SDKs are coming soon! In the meantime, you can use the API directly with any HTTP client.
</Info>

### Community Libraries

| Language           | Library     | Status |
| ------------------ | ----------- | ------ |
| JavaScript/Node.js | Coming Soon | 🚧     |
| Python             | Coming Soon | 🚧     |
| PHP                | Coming Soon | 🚧     |
| Ruby               | Coming Soon | 🚧     |

***

## Need Help?

<CardGroup cols={2}>
  <Card title="Support" icon="envelope" href="mailto:support@mailgreet.com">
    Contact our support team
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Browse the full documentation
  </Card>
</CardGroup>