---
title: "Add a new subscriber (direct add)"
method: POST
path: "/subscribers"
tags: ["Subscribers"]
---

# Add a new subscriber (direct add)

`POST /subscribers`

## Request

- Base URL: `https://api.maildroppa.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.maildroppa.com/subscribers`
- Auth: API key in header `X-API-Key`

Creates a subscriber entry immediately, without double opt-in.
When the daily direct-add quota is exceeded, the request fails with a guidance message
to use CSV import or the /subscribers/opt-in endpoint.

## Request body

- AddSubscriber: Subscriber to create with typed subscriber field values, tags, and status.
  - `email` string: Subscriber email address.
  - `firstName` string: Subscriber first name.
  - `fields` FieldValueInput[]: Typed field values for the subscriber.
    - `fieldId` string, uuid
    - `value` union: Strict typed subscriber field value accepted by write endpoints.
      - object: Text subscriber field value.
        - `kind` 'TEXT' | 'EMAIL' | 'NUMBER' | 'DATE' | 'BOOLEAN' | 'SINGLE_OPTION' | 'MULTI_OPTION', required: Typed value category used when reading or writing subscriber field values.
        - `text` string, required: Text value.
      - object: Email subscriber field value.
        - `kind` 'TEXT' | 'EMAIL' | 'NUMBER' | 'DATE' | 'BOOLEAN' | 'SINGLE_OPTION' | 'MULTI_OPTION', required: Typed value category used when reading or writing subscriber field values.
        - `text` string, required: Email value.
      - object: Number subscriber field value.
        - `kind` 'TEXT' | 'EMAIL' | 'NUMBER' | 'DATE' | 'BOOLEAN' | 'SINGLE_OPTION' | 'MULTI_OPTION', required: Typed value category used when reading or writing subscriber field values.
        - `number` number, required: Number value.
      - object: Date subscriber field value.
        - `kind` 'TEXT' | 'EMAIL' | 'NUMBER' | 'DATE' | 'BOOLEAN' | 'SINGLE_OPTION' | 'MULTI_OPTION', required: Typed value category used when reading or writing subscriber field values.
        - `date` string, date, required
      - object: Boolean subscriber field value.
        - `kind` 'TEXT' | 'EMAIL' | 'NUMBER' | 'DATE' | 'BOOLEAN' | 'SINGLE_OPTION' | 'MULTI_OPTION', required: Typed value category used when reading or writing subscriber field values.
        - `booleanValue` boolean, required: Boolean value.
      - object: Single-option subscriber field value.
        - `kind` 'TEXT' | 'EMAIL' | 'NUMBER' | 'DATE' | 'BOOLEAN' | 'SINGLE_OPTION' | 'MULTI_OPTION', required: Typed value category used when reading or writing subscriber field values.
        - `optionId` string, uuid, required
      - object: Multi-option subscriber field value.
        - `kind` 'TEXT' | 'EMAIL' | 'NUMBER' | 'DATE' | 'BOOLEAN' | 'SINGLE_OPTION' | 'MULTI_OPTION', required: Typed value category used when reading or writing subscriber field values.
        - `optionIds` string[], required: Selected option IDs.
  - `tags` string[]: List of tag identifiers associated with the subscriber.
  - `subscriberStatus` 'PENDING' | 'CONFIRMED' | 'UNSUBSCRIBED' | 'COLD' | 'BOUNCED' | 'SOFT_BOUNCED' | 'BLOCKED' | 'DELETED'
  - `topicIds` string[]: Active topic ids the subscriber joins. Missing means the tenant default topic.

## Response `200`

Subscriber created.

- Subscriber: Represents subscriber information including fields, tags, and status.
  - `id` string, uuid
  - `values` SubscriberFieldValue[]: Subscriber field display values for the subscriber. Use subscriber field value endpoints for typed values and option IDs.
    - `id` string, uuid
    - `personalizationTagName` string: Stable subscriber personalization tag name returned in the personalizationTagName property.
    - `value` string: Display value for this field. Choice and multi-select values are returned as labels for display; use subscriber field value endpoints for typed option IDs.
  - `tags` string[]: List of tag identifiers associated with the subscriber.
  - `subscriberStatus` 'PENDING' | 'CONFIRMED' | 'UNSUBSCRIBED' | 'COLD' | 'BOUNCED' | 'SOFT_BOUNCED' | 'BLOCKED' | 'DELETED'
  - `registeredAt` string: Registration date/time of the subscriber.
  - `lastImportedAtUtc` string, date-time
  - `gdprAgreement` string: Text of GDPR agreement if applicable.

## Other responses

- `400`: Invalid subscriber data or quota exceeded.
- `401`: Not Authorized
- `403`: Not Allowed
- `428`: Accept the customer agreements in the app before using API keys.

---

[API](https://skmtc.dev/maildroppa/apis/maildroppa-api-beta.md) · [All operations](https://skmtc.dev/maildroppa/apis/maildroppa-api-beta/llms.txt) · [OpenAPI document](https://skmtc.dev/maildroppa/apis/maildroppa-api-beta/revisions/a9f5a3fd1fb0?raw)