API Introduction

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.

Quick Start

Get up and running in 5 minutes

Authentication

Learn how to authenticate your requests

Subscribers API

Manage your subscriber list

Postman Collection

Download and test the API

Base URL

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

Production

https://api.mailgreet.com/api/v1/external

Authentication

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

Getting Your API Key

Log in to your MailGreet Dashboard
Navigate to Settings → Integrations
Click “Generate New API Key”
Copy and securely store your API key

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

Using Your API Key

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

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:

curl -X GET "https://api.mailgreet.com/api/v1/external/test-auth" \
  -H "Authorization: Bearer YOUR_API_KEY"

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);

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())

$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;

Successful Response:

{
  "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:

Get Your API Key

Generate your API key from the Integrations page in your dashboard.

Test Authentication

Verify your API key works by calling the /test-auth endpoint.

Create Your First Subscriber

Add a subscriber using the Subscribers API.

Start Building

Explore the full API to build powerful integrations.

Your First API Call

Here’s how to create a subscriber:

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

{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Optional success message"
}

Error Response

{
  "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.

Implement exponential backoff in your applications to handle rate limiting gracefully.

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:

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

Available Endpoints

Authentication

Test API key authentication

Subscribers

Create, read, update, delete subscribers

Health Check

Check API availability (no auth required)

Plans

View available subscription plans

Postman Collection

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

Download Postman Collection

Import into Postman and start testing immediately

Setup Instructions

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

SDKs & Libraries

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

Community Libraries

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

Getting Started

Authentication

Subscribers

Webhooks

Health Check

Welcome to the MailGreet API

Quick Start

Authentication

Subscribers API

Postman Collection

Base URL

Authentication

Getting Your API Key

Using Your API Key

Test Your Authentication

Quick Start

Your First API Call

Response Format

Success Response

Error Response

HTTP Status Codes

Rate Limiting

Available Endpoints

Authentication

Subscribers

Health Check

Plans

Postman Collection

Download Postman Collection

Setup Instructions

SDKs & Libraries

Community Libraries

Need Help?

Support

Documentation

​Welcome to the MailGreet API

Quick Start

Authentication

Subscribers API

Postman Collection

​Base URL

​Authentication

​Getting Your API Key

​Using Your API Key

​Test Your Authentication

​Quick Start

​Your First API Call

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Rate Limiting

​Pagination

​Available Endpoints

Authentication

Subscribers

Health Check

Plans

​Postman Collection

Download Postman Collection

​Setup Instructions

​SDKs & Libraries

​Community Libraries

​Need Help?

Support

Documentation

Welcome to the MailGreet API

Base URL

Authentication

Getting Your API Key

Using Your API Key

Test Your Authentication

Quick Start

Your First API Call

Response Format

Success Response

Error Response

HTTP Status Codes

Rate Limiting

Pagination

Available Endpoints

Postman Collection

Setup Instructions

SDKs & Libraries

Community Libraries

Need Help?