Resources

Subscriber management API

Create, list, update and delete subscribers on a list, including bulk operations.

How subscribers work

A subscriber is a person on one of your email lists: their email address, name, status, tags and any custom fields you have defined on the list. Subscribers always belong to a specific list, which is why every endpoint below takes a listId in the path. The same email address can exist on several lists as separate subscriber records.

The Subscribers API is the workhorse of most integrations: it is how signups from your own website, app or backend reach the platform, and how you keep profile data in sync with external systems. For one-off changes use the single-subscriber endpoints; for imports and synchronization jobs use the bulk endpoint, which processes up to 1,000 subscribers per request.

Use cases

Add a newsletter signup from your own form or checkout flow, with double opt-in handled automatically.
Migrate an existing audience from another platform in batches of up to 1,000 with the bulk endpoint.
Keep profile data (names, tags, custom fields) in sync with your CRM or webshop.
Honor unsubscribe requests collected outside the platform by updating the status.
Look up a subscriber before sending, for example to check their status or custom fields.

The subscriber object

Every subscriber has these core fields:

Name	Type	Description
`id`	string	Unique subscriber id (UUID). Assigned by the platform.
`email`	string	The subscriber’s email address. Unique per list.
`first_name / last_name`	string	Optional name fields, available as {{firstName}} and {{lastName}} merge tags in emails.
`status`	string	Sending eligibility - see the status table below. Only active subscribers receive campaigns.
`tags`	string[]	Free-form labels, for example customer or vip. Usable in segment rules.
`custom_fields`	object	Key-value data specific to your account, for example company or phone. Define the field names on the list.
`created_at`	string	When the subscriber was added (UTC).

The status field controls whether the platform will send to the address:

Name	Type	Description
`active`	status	Confirmed and sendable. Receives campaigns and automations.
`inactive`	status	Not sendable. Also the holding status while a double opt-in confirmation is pending.
`unsubscribed`	status	Opted out. Never emailed again unless they resubscribe themselves.
`complained`	status	Marked an email as spam. Permanently excluded from sending.
`bounced`	status	The address hard-bounced. Excluded to protect your sender reputation.
`blacklisted`	status	On your suppression list (see the Blacklist API).

Statuses protect your deliverability

The API lets you set an explicit status, but never move complained, bounced or unsubscribed contacts back to active unless the person has genuinely re-consented. Mailbox providers penalize senders who email recycled complainers, and that affects your whole account.

Double opt-in behavior

If your account has double opt-in enabled (Settings, GDPR), subscribers created through the API start as inactive with a pending confirmation, and the platform automatically sends them a confirmation email. They become active when they click the link. The create response includes confirmation_required and confirmation_email_sent so your integration knows what happened.

When importing contacts who already gave consent elsewhere, pass skip_confirmation: true or an explicit status to add them directly without a new confirmation email.

Endpoints

GET

Get subscribers

/subscriber-api/{listId}

Retrieve all subscribers from a list with optional filtering and pagination.

Query parameters

Name	Type	Description
`listId`required	string	Email list id (path).
`status`	string	Filter by status (active, inactive, blacklisted, unsubscribed).
`search`	string	Search in email, first_name, last_name.
`page`	number	Page number (default: 1).
`limit`	number	Results per page (default: 25, max: 100).

curl -X GET "https://api.mailingplatform.net/subscriber-api/your-list-id?status=active&page=1" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json"

GET

Get single subscriber

/subscriber-api/{listId}/{subscriberId}

Retrieve a specific subscriber by their ID.

Name	Type	Description
`listId`required	string	Email list id (path).
`subscriberId`required	string	Subscriber id (path).

curl -X GET "https://api.mailingplatform.net/subscriber-api/{listId}/{subscriberId}" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json"

POST

Create subscriber

/subscriber-api/{listId}

Add a new subscriber to a list. If your account has double opt-in enabled (Settings, GDPR), new subscribers start as pending and automatically receive a confirmation email; they become active when they click the link. Pass skip_confirmation: true or an explicit status to add subscribers directly, for example when migrating contacts who already confirmed elsewhere.

Request body

Name	Type	Description
`email`required	string	Subscriber email address.
`first_name`	string	First name.
`last_name`	string	Last name.
`tags`	string[]	Optional tags, for example customer, newsletter.
`custom_fields`	object	List-specific custom fields.
`skip_confirmation`	boolean	Skip the double opt-in confirmation email.
`status`	string	Explicit status when adding a subscriber directly.

The response includes confirmation_required and confirmation_email_sent so you know whether the subscriber still needs to confirm.

curl -X POST "https://api.mailingplatform.net/subscriber-api/{listId}" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "tags": ["customer", "newsletter"],
  "custom_fields": {
    "company": "Acme Corp",
    "phone": "+1234567890"
  },
  "skip_confirmation": false
}'

PUT

Update subscriber

/subscriber-api/{listId}/{subscriberId}

Update an existing subscriber's information.

Request body (partial)

Name	Type	Description
`first_name`	string	Updated first name.
`status`	string	Updated status, for example inactive.
`custom_fields`	object	Updated custom fields.

curl -X PUT "https://api.mailingplatform.net/subscriber-api/{listId}/{subscriberId}" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "John Updated",
  "status": "inactive",
  "custom_fields": {
    "company": "New Company"
  }
}'

DELETE

Delete subscriber

/subscriber-api/{listId}/{subscriberId}

Remove a subscriber from the list permanently.

curl -X DELETE "https://api.mailingplatform.net/subscriber-api/{listId}/{subscriberId}" \
  -H "Authorization: Bearer mp_live_..."

POST

Bulk operations

/bulk-subscriber-api/{listId}

Perform bulk operations on multiple subscribers at once. Maximum 1,000 items per request; limited to 10 requests per minute. unsubscribe sets the subscriber's status to unsubscribed.

Partial success is normal

Bulk requests do not fail as a whole when single items are invalid. The response contains a results array with one entry per subscriber plus a summary with successful and failed counts - always check it when synchronizing, so rejected rows are not silently lost.

Supported actions

Name	Type	Description
`add`	action	Add multiple subscribers.
`update`	action	Update multiple subscribers.
`delete`	action	Delete multiple subscribers.
`unsubscribe`	action	Unsubscribe multiple subscribers.

Example: bulk add

curl -X POST "https://api.mailingplatform.net/bulk-subscriber-api/{listId}" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "action": "add",
  "subscribers": [
    {
      "email": "user1@example.com",
      "first_name": "User",
      "last_name": "One",
      "status": "active"
    },
    {
      "email": "user2@example.com",
      "first_name": "User",
      "last_name": "Two",
      "status": "active"
    }
  ]
}'