Create up to 100 subscribers in a single request

POST

/api/subscribers/bulk

Each item may carry customFields. An item with unknown keys or invalid values is
rejected on its own with reason INVALID_CUSTOM_FIELDS, and the rest of the batch
is still created.

Request

Authorization

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Bulk create completed. failed lists the rejected items and is empty when every item succeeded.

Bodyapplication/json

🟠400ValidationError

🟠401Unauthorized

🟠403EmailNotVerified

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.maildesk.io/api/subscribers/bulk' \
--header 'Content-Type: application/json' \
--data-raw '{
    "subscribers": [
        {
            "email": "ada@yourcompany.com",
            "firstName": "Ada",
            "lastName": "Lovelace",
            "isConfirmed": true,
            "customFields": {
                "latest_destination": "Rome"
            }
        },
        {
            "email": "alan@yourcompany.com",
            "firstName": "Alan",
            "lastName": "Turing",
            "isConfirmed": true,
            "customFields": {
                "not_a_field": "x"
            }
        }
    ]
}'

Response Example

200 - Success

{
    "failed": [
        {
            "index": 1,
            "email": "alan@yourcompany.com",
            "reason": "INVALID_CUSTOM_FIELDS"
        }
    ]
}

Modified at 2026-10-08 06:32:39

Create a new subscriber

Get a subscriber by ID