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"
}
Subscribers
Create Subscriber
Add a new subscriber to your mailing list
POST
/
api
/
v1
/
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 anactive 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
string
required
Bearer token. Format:
Bearer YOUR_API_KEYRequest Body
string
required
A valid email address for the subscriber. Must be unique within your account.
string
The subscriber’s first name.
string
The subscriber’s last name.
string
The subscriber’s phone number. Recommended format:
+1234567890array
An array of group UUIDs to add the subscriber to.Example:
["550e8400-e29b-41d4-a716-446655440000"]object
An object containing custom field key-value pairs. Keys must match your defined custom fields.Example:
{"company": "Acme Inc", "role": "Developer"}Response
boolean
Indicates if the subscriber was created successfully
object
Show Subscriber object
Show Subscriber object
string
Unique identifier (UUID) for the subscriber
string
The subscriber’s email address
string
The subscriber’s first name
string
The subscriber’s last name
string
The subscriber’s phone number
string
Subscriber status:
active, unsubscribed, bounced, or complainedstring
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"
}