Skip to main content

​
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
Development
http://localhost:8001/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

  1. Log in to your MailGreet Dashboard
  2. Navigate to Settings → Integrations
  3. Click “Generate New API Key”
  4. 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"
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:
1

Get Your API Key

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

Test Authentication

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

Create Your First Subscriber

Add a subscriber using the Subscribers API.
4

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 CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing API key
403Forbidden - API key lacks required permissions or limit exceeded
404Not Found - Resource doesn’t exist
422Unprocessable Entity - Validation error
429Too Many Requests - Rate limit exceeded
500Internal 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:
PlanRate Limit
Free60 requests/minute
Starter300 requests/minute
Pro600 requests/minute
EnterpriseCustom
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:
ParameterTypeDefaultDescription
pageinteger1Page number
per_pageinteger20Items 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

  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

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

​
Community Libraries

LanguageLibraryStatus
JavaScript/Node.jsComing Soon🚧
PythonComing Soon🚧
PHPComing Soon🚧
RubyComing Soon🚧

​
Need Help?

Support

Contact our support team

Documentation

Browse the full documentation