> ## 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.

# Create Subscriber

> Add a new subscriber to your mailing list

## 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.

<Note>
  This endpoint respects your plan's subscriber limits. If you've reached your limit, a `403 Forbidden` error will be returned.
</Note>

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token. Format: `Bearer YOUR_API_KEY`
</ParamField>

## Request Body

<ParamField body="email" type="string" required>
  A valid email address for the subscriber. Must be unique within your account.
</ParamField>

<ParamField body="first_name" type="string">
  The subscriber's first name.
</ParamField>

<ParamField body="last_name" type="string">
  The subscriber's last name.
</ParamField>

<ParamField body="phone" type="string">
  The subscriber's phone number. Recommended format: `+1234567890`
</ParamField>

<ParamField body="group_ids" type="array">
  An array of group UUIDs to add the subscriber to.

  Example: `["550e8400-e29b-41d4-a716-446655440000"]`
</ParamField>

<ParamField body="custom_fields" type="object">
  An object containing custom field key-value pairs. Keys must match your defined custom fields.

  Example: `{"company": "Acme Inc", "role": "Developer"}`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the subscriber was created successfully
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="Subscriber object">
    <ResponseField name="id" type="string">
      Unique identifier (UUID) for the subscriber
    </ResponseField>

    <ResponseField name="email" type="string">
      The subscriber's email address
    </ResponseField>

    <ResponseField name="first_name" type="string">
      The subscriber's first name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      The subscriber's last name
    </ResponseField>

    <ResponseField name="phone" type="string">
      The subscriber's phone number
    </ResponseField>

    <ResponseField name="status" type="string">
      Subscriber status: `active`, `unsubscribed`, `bounced`, or `complained`
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the subscriber was created
    </ResponseField>
  </Expandable>
</ResponseField>

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

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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;
  ```
</RequestExample>

<ResponseExample>
  ```json 201 - Created theme={null}
  {
    "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"
    }
  }
  ```

  ```json 400 - Validation Error theme={null}
  {
    "success": false,
    "error": "Validation failed",
    "data": {
      "email": ["The email field is required."]
    }
  }
  ```

  ```json 403 - Limit Exceeded theme={null}
  {
    "success": false,
    "error": "Subscriber limit exceeded. Please upgrade your plan.",
    "data": {
      "current_count": 100,
      "limit": 100
    }
  }
  ```

  ```json 409 - Duplicate Email theme={null}
  {
    "success": false,
    "error": "A subscriber with this email already exists"
  }
  ```
</ResponseExample>