> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.outpost.pub/llms.txt
> Use this file to discover all available pages before exploring further.

# Members API

> Create, retrieve, update, and delete members via the Outpost Integration API.

## Get a member

Retrieve a single member by email address (or custom ID in Custom ID mode).

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /integration/members/{identifier}
Authorization: Bearer your_integration_key
```

**Path parameters:**

| Parameter    | Description                                                                         |
| ------------ | ----------------------------------------------------------------------------------- |
| `identifier` | Member's email address, or custom member ID if your integration uses Custom ID mode |

**Response (200):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "data": {
    "guid": "abc-123-def",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "is_subscribed": true,
    "note": "Subscriber since launch",
    "labels": ["newsletter", "podcast-listener"],
    "tier_id": "prod_abc123",
    "member_id": null,
    "status": "paid",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-03-01T14:20:00Z"
  },
  "message": "Member retrieved successfully."
}
```

**Error (404):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": false,
  "message": "Member not found."
}
```

***

## Create a member

Create a new free member. The member is automatically synced to Ghost.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /integration/members
Authorization: Bearer your_integration_key
Content-Type: application/json

{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "is_subscribed": true,
  "note": "Signed up via partner form",
  "labels": ["partner", "newsletter"],
  "tier_id": null
}
```

**Request body:**

| Field           | Type           | Required            | Description                                                                                                                                    |
| --------------- | -------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`         | string         | Yes                 | Member's email address. Must be unique (unless your integration allows duplicate emails in Custom ID mode).                                    |
| `name`          | string         | No                  | Full name                                                                                                                                      |
| `is_subscribed` | boolean        | No                  | Subscribe to newsletters (default varies by integration)                                                                                       |
| `newsletters`   | array          | No                  | Per-newsletter assignments: objects with a required newsletter `id` (string) and an optional `status` (string). Accepted on create and update. |
| `note`          | string         | No                  | Notes or description. Omit the field if you don't want to set a note: sending `null` will fail validation.                                     |
| `labels`        | array          | No                  | Label names to apply. Labels are created automatically if they don't exist.                                                                    |
| `tier_id`       | string \| null | No                  | Stripe product ID to associate the member with a tier. Pass `null` to leave the member free.                                                   |
| `member_id`     | string         | Custom ID mode only | Required when your integration uses Custom ID mode. Your external system's unique identifier for this member.                                  |

**Response (200):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "data": {
    "guid": "abc-123-def",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "is_subscribed": true,
    "note": "Signed up via partner form",
    "labels": ["partner", "newsletter"],
    "tier_id": null,
    "status": "free",
    "created_at": "2026-03-16T10:30:00Z",
    "updated_at": "2026-03-16T10:30:00Z"
  },
  "message": "Member created successfully."
}
```

**Validation error:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": false,
  "message": "The email has already been taken."
}
```

The response body uses the same `success: false` shape for any failed request. Inspect `message` to surface the reason to your caller.

<Note>
  Creating a member via the API creates a **free member**. Paid subscriptions require a Stripe checkout. You can set `tier_id` to associate the member with a tier, but billing is handled separately through Stripe.
</Note>

***

## Update a member

Update an existing member's information. Only include the fields you want to change.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
PUT /integration/members/{identifier}
Authorization: Bearer your_integration_key
Content-Type: application/json

{
  "name": "Jane Williams",
  "labels": ["partner", "newsletter", "annual-reader"]
}
```

**Path parameters:**

| Parameter    | Description                                                                         |
| ------------ | ----------------------------------------------------------------------------------- |
| `identifier` | Member's email address, or custom member ID if your integration uses Custom ID mode |

**Request body:**

| Field           | Type           | Description                    |
| --------------- | -------------- | ------------------------------ |
| `email`         | string         | Updated email address          |
| `name`          | string         | Updated name                   |
| `is_subscribed` | boolean        | Update newsletter subscription |
| `note`          | string         | Updated notes                  |
| `labels`        | array          | Updated label list             |
| `tier_id`       | string \| null | Updated tier association       |

All fields are optional: only send the fields you want to change.

<Warning>
  The `labels` field **replaces** the member's entire label set. To add a label without removing existing ones, first retrieve the member, merge your new label into the existing list, then send the combined array.
</Warning>

**Response (200):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "data": {
    "guid": "abc-123-def",
    "email": "jane@example.com",
    "name": "Jane Williams",
    "is_subscribed": true,
    "note": "Signed up via partner form",
    "labels": ["partner", "newsletter", "annual-reader"],
    "tier_id": null,
    "status": "free",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-03-16T14:45:00Z"
  },
  "message": "Member updated successfully."
}
```

***

## Delete a member

Permanently delete a member from Outpost and Ghost.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
DELETE /integration/members/{identifier}
Authorization: Bearer your_integration_key
```

**Path parameters:**

| Parameter    | Description                                                                         |
| ------------ | ----------------------------------------------------------------------------------- |
| `identifier` | Member's email address, or custom member ID if your integration uses Custom ID mode |

**Response (200):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "data": [],
  "message": "Member deleted successfully."
}
```

**What gets deleted:**

* Member record in Outpost
* Member record in Ghost
* All labels and relationships

**What's preserved:**

* Stripe customer and payment records (retained for financial compliance)
* Mailgun email delivery logs

<Warning>
  Deletion is **permanent and irreversible**. For members who are simply cancelling, consider removing their tier or unsubscribing them instead.
</Warning>

***

## Response codes

| Code  | Meaning                                                                                                                                                                        |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200` | Success: also returned with `"success": false` for validation failures and other handled errors. Always inspect the response body's `success` field, not just the HTTP status. |
| `401` | Invalid or missing integration key                                                                                                                                             |
| `404` | Member not found                                                                                                                                                               |
| `429` | Rate limit exceeded (30 requests/minute)                                                                                                                                       |
| `500` | Unhandled server error                                                                                                                                                         |