Create 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",
    "phone": "+1234567890",
    "group_ids": ["550e8400-e29b-41d4-a716-446655440000"],
    "custom_fields": {
      "company": "Acme Inc",
      "role": "Marketing Manager"
    }
  }'

const response = await fetch('https://api.mailgreet.com/api/v1/external/subscribers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'john@example.com',
    first_name: 'John',
    last_name: 'Doe',
    phone: '+1234567890',
    group_ids: ['550e8400-e29b-41d4-a716-446655440000'],
    custom_fields: {
      company: 'Acme Inc',
      role: 'Marketing Manager'
    }
  })
});

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

import requests

payload = {
    'email': 'john@example.com',
    'first_name': 'John',
    'last_name': 'Doe',
    'phone': '+1234567890',
    'group_ids': ['550e8400-e29b-41d4-a716-446655440000'],
    'custom_fields': {
        'company': 'Acme Inc',
        'role': 'Marketing Manager'
    }
}

response = requests.post(
    'https://api.mailgreet.com/api/v1/external/subscribers',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=payload
)

print(response.json())

<?php
$payload = json_encode([
    'email' => 'john@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'phone' => '+1234567890',
    'group_ids' => ['550e8400-e29b-41d4-a716-446655440000'],
    'custom_fields' => [
        'company' => 'Acme Inc',
        'role' => 'Marketing Manager'
    ]
]);

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.mailgreet.com/api/v1/external/subscribers',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

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

echo $response;

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "status": "active",
    "created_at": "2026-01-18T12:00:00Z"
  }
}

{
  "success": false,
  "error": "Validation failed",
  "data": {
    "email": ["The email field is required."]
  }
}

{
  "success": false,
  "error": "Subscriber limit exceeded. Please upgrade your plan.",
  "data": {
    "current_count": 100,
    "limit": 100
  }
}

{
  "success": false,
  "error": "A subscriber with this email already exists"
}

POST

api

external

subscribers

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",
    "phone": "+1234567890",
    "group_ids": ["550e8400-e29b-41d4-a716-446655440000"],
    "custom_fields": {
      "company": "Acme Inc",
      "role": "Marketing Manager"
    }
  }'

const response = await fetch('https://api.mailgreet.com/api/v1/external/subscribers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'john@example.com',
    first_name: 'John',
    last_name: 'Doe',
    phone: '+1234567890',
    group_ids: ['550e8400-e29b-41d4-a716-446655440000'],
    custom_fields: {
      company: 'Acme Inc',
      role: 'Marketing Manager'
    }
  })
});

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

import requests

payload = {
    'email': 'john@example.com',
    'first_name': 'John',
    'last_name': 'Doe',
    'phone': '+1234567890',
    'group_ids': ['550e8400-e29b-41d4-a716-446655440000'],
    'custom_fields': {
        'company': 'Acme Inc',
        'role': 'Marketing Manager'
    }
}

response = requests.post(
    'https://api.mailgreet.com/api/v1/external/subscribers',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=payload
)

print(response.json())

<?php
$payload = json_encode([
    'email' => 'john@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'phone' => '+1234567890',
    'group_ids' => ['550e8400-e29b-41d4-a716-446655440000'],
    'custom_fields' => [
        'company' => 'Acme Inc',
        'role' => 'Marketing Manager'
    ]
]);

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.mailgreet.com/api/v1/external/subscribers',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

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

echo $response;

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "status": "active",
    "created_at": "2026-01-18T12:00:00Z"
  }
}

{
  "success": false,
  "error": "Validation failed",
  "data": {
    "email": ["The email field is required."]
  }
}

{
  "success": false,
  "error": "Subscriber limit exceeded. Please upgrade your plan.",
  "data": {
    "current_count": 100,
    "limit": 100
  }
}

{
  "success": false,
  "error": "A subscriber with this email already exists"
}

Overview

Create a new subscriber in your MailGreet account. The subscriber will be added with an active status by default and can optionally be assigned to one or more groups.

This endpoint respects your plan’s subscriber limits. If you’ve reached your limit, a 403 Forbidden error will be returned.

Authentication

Authorization

string

required

Bearer token. Format: Bearer YOUR_API_KEY

Request Body

string

required

A valid email address for the subscriber. Must be unique within your account.

first_name

string

The subscriber’s first name.

last_name

string

The subscriber’s last name.

phone

string

The subscriber’s phone number. Recommended format: +1234567890

group_ids

array

An array of group UUIDs to add the subscriber to.Example: ["550e8400-e29b-41d4-a716-446655440000"]

custom_fields

object

An object containing custom field key-value pairs. Keys must match your defined custom fields.Example: {"company": "Acme Inc", "role": "Developer"}

Response

success

boolean

Indicates if the subscriber was created successfully

data

object

Show Subscriber object

string

Unique identifier (UUID) for the subscriber

string

The subscriber’s email address

first_name

string

The subscriber’s first name

last_name

string

The subscriber’s last name

phone

string

The subscriber’s phone number

status

string

Subscriber status: active, unsubscribed, bounced, or complained

created_at

string

ISO 8601 timestamp of when the subscriber was created

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",
    "phone": "+1234567890",
    "group_ids": ["550e8400-e29b-41d4-a716-446655440000"],
    "custom_fields": {
      "company": "Acme Inc",
      "role": "Marketing Manager"
    }
  }'

const response = await fetch('https://api.mailgreet.com/api/v1/external/subscribers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'john@example.com',
    first_name: 'John',
    last_name: 'Doe',
    phone: '+1234567890',
    group_ids: ['550e8400-e29b-41d4-a716-446655440000'],
    custom_fields: {
      company: 'Acme Inc',
      role: 'Marketing Manager'
    }
  })
});

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

import requests

payload = {
    'email': 'john@example.com',
    'first_name': 'John',
    'last_name': 'Doe',
    'phone': '+1234567890',
    'group_ids': ['550e8400-e29b-41d4-a716-446655440000'],
    'custom_fields': {
        'company': 'Acme Inc',
        'role': 'Marketing Manager'
    }
}

response = requests.post(
    'https://api.mailgreet.com/api/v1/external/subscribers',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=payload
)

print(response.json())

<?php
$payload = json_encode([
    'email' => 'john@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'phone' => '+1234567890',
    'group_ids' => ['550e8400-e29b-41d4-a716-446655440000'],
    'custom_fields' => [
        'company' => 'Acme Inc',
        'role' => 'Marketing Manager'
    ]
]);

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.mailgreet.com/api/v1/external/subscribers',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

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

echo $response;

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "status": "active",
    "created_at": "2026-01-18T12:00:00Z"
  }
}

{
  "success": false,
  "error": "Validation failed",
  "data": {
    "email": ["The email field is required."]
  }
}

{
  "success": false,
  "error": "Subscriber limit exceeded. Please upgrade your plan.",
  "data": {
    "current_count": 100,
    "limit": 100
  }
}

{
  "success": false,
  "error": "A subscriber with this email already exists"
}

Get Subscriber Update Subscriber

Getting Started

Authentication

Subscribers

Webhooks

Health Check

Overview

Authentication

Request Body

Response

​Overview

​Authentication

​Request Body

​Response

Overview

Authentication

Request Body

Response