How do tags work in the Subscribe API?

Mailpuff calls them tags everywhere you read them. The API fields keep their internal names, group_id and group_ids, and you can use either or both. Unknown ids are ignored, and leaving them out adds the person with no tag. With the API key, only public tags are given: the ones offered on signup forms and the preferences page. Internal tag ids are ignored, so a leaked key can't put people on private lists. Tags go to new and existing subscribers alike, so posting an address again is a safe way to give someone another tag. To find tag ids, ask your AI agent to run list-audiences, or call GET /wp-json/mailpuff/v1/groups as an administrator.

Mailpuff

Mailpuff Subscribe API: Add Subscribers From Any Site or App

Q: Where do I find my API key?

Open Mailpuff → Settings → MCP & API and look under Subscribe API. The key starts with mailpuff_. The screen also shows when the key was created and when it was last used. Anyone with the key can add people to your list, so keep it on a server. Don't put it in JavaScript that runs in a visitor's browser. If the key leaks, press Regenerate. The old key stops working at once.

Q: How do I add a subscriber?

If a tool can't set custom headers, send the key as an api_key field in the JSON body instead.

Q: What does the API return?

The answer is the subscriber, with no wrapper. Use the new field to tell a new subscriber from one you already had. An existing subscriber keeps their status. Someone who unsubscribed is never quietly signed up again.

Q: Which errors can the API return?

Errors use the standard WordPress shape: { "code": "...", "message": "...", "data": { "status": 400 } }.

Q: Does the Subscribe API send a confirmation email?

No. A new address joins as subscribed straight away, with its source recorded as the API. That suits people who already agreed somewhere else, such as a checkbox at checkout. For a public signup form on your WordPress site, use the Newsletter signup block, which uses double opt-in.

Q: Can I react when the API adds someone?

Yes. A new subscriber fires do_action( 'mailpuff_contact_created', $contact_id, 'subscribe' ). Hook it from your own plugin to sync the person elsewhere. The hooks reference lists every hook Mailpuff fires.

Add subscribers to your Mailpuff list from another website, app or script with one POST request and an API key. Fields, tags, responses, errors, the rate limit and code examples.

The Mailpuff Subscribe API adds a subscriber to your WordPress newsletter with one HTTP request. Send a POST to /wp-json/mailpuff/v1/subscribe with the person’s email and your API key in the X-Mailpuff-Key header. It works from another website, a mobile app, a checkout script or an automation tool, with no WordPress login. Re-sending an address that’s already on your list never creates a duplicate.

Where do I find my API key?

Open Mailpuff → Settings → MCP & API and look under Subscribe API. The key starts with mailpuff_. The screen also shows when the key was created and when it was last used.

Anyone with the key can add people to your list, so keep it on a server. Don’t put it in JavaScript that runs in a visitor’s browser. If the key leaks, press Regenerate. The old key stops working at once.

How do I add a subscriber?

POST https://your-site.com/wp-json/mailpuff/v1/subscribe
X-Mailpuff-Key: mailpuff_your_key_here
Content-Type: application/json

{
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "group_ids": [5, 7]
}

If a tool can’t set custom headers, send the key as an api_key field in the JSON body instead.

Which fields does the request take?

Field	Type	Required	What it is
`email`	string	Yes	The subscriber’s email address
`first_name`	string	No	First name
`last_name`	string	No	Last name
`group_id`	integer	No	One tag to give the person
`group_ids`	array or string	No	Several tags, as `[5, 7]` or `"5,7"`

Mailpuff calls them tags everywhere you read them. The API fields keep their internal names, group_id and group_ids, and you can use either or both. Unknown ids are ignored, and leaving them out adds the person with no tag.

With the API key, only public tags are given: the ones offered on signup forms and the preferences page. Internal tag ids are ignored, so a leaked key can’t put people on private lists.
Tags go to new and existing subscribers alike, so posting an address again is a safe way to give someone another tag.
To find tag ids, ask your AI agent to run list-audiences, or call GET /wp-json/mailpuff/v1/groups as an administrator.

What does the API return?

The answer is the subscriber, with no wrapper. Use the new field to tell a new subscriber from one you already had.

Status	When	Body
`201 Created`	A new subscriber was added	`{ "id": 123, "email": "[email protected]", "status": "subscribed", "new": true }`
`200 OK`	The address was already on your list. Nothing was duplicated, and tags were added	`{ "id": 123, "email": "[email protected]", "status": "subscribed", "new": false }`
`200 OK`	The address unsubscribed, bounced or was erased before. It is not added back	`{ "id": 0, "email": "[email protected]", "status": "unsubscribed", "new": false, "suppressed": true }`

An existing subscriber keeps their status. Someone who unsubscribed is never quietly signed up again.

Which errors can the API return?

Errors use the standard WordPress shape: { "code": "...", "message": "...", "data": { "status": 400 } }.

Status	Code	Cause
401	`invalid_key`	The API key is missing or wrong
400	`invalid_email`	The email is missing or malformed
429	`rate_limit`	More than 10 requests in a minute from one IP address
500	`create_failed`	The database insert failed

What is the rate limit?

The Subscribe API takes 10 requests per minute from each IP address. Past that it answers 429, so wait a minute and retry. To move a whole list, use Mailpuff → Subscribers → Import with a CSV file instead of looping over the API.

No. A new address joins as subscribed straight away, with its source recorded as the API. That suits people who already agreed somewhere else, such as a checkbox at checkout. For a public signup form on your WordPress site, use the Newsletter signup block, which uses double opt-in.

Code examples

cURL

curl -X POST https://your-site.com/wp-json/mailpuff/v1/subscribe 
  -H "X-Mailpuff-Key: mailpuff_your_key_here" 
  -H "Content-Type: application/json" 
  -d '{ "email": "[email protected]", "first_name": "Jane", "group_ids": [5, 7] }'

PHP (from another WordPress site)

$response = wp_remote_post(
    'https://your-site.com/wp-json/mailpuff/v1/subscribe',
    array(
        'headers' => array(
            'X-Mailpuff-Key' => 'mailpuff_your_key_here',
            'Content-Type'   => 'application/json',
        ),
        'body'    => wp_json_encode(
            array(
                'email'     => '[email protected]',
                'group_ids' => array( 5, 7 ),
            )
        ),
    )
);
$code       = wp_remote_retrieve_response_code( $response ); // 201 or 200
$subscriber = json_decode( wp_remote_retrieve_body( $response ), true );

Node.js (server side)

const res = await fetch( 'https://your-site.com/wp-json/mailpuff/v1/subscribe', {
  method: 'POST',
  headers: {
    'X-Mailpuff-Key': process.env.MAILPUFF_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify( { email: '[email protected]', first_name: 'Jane' } ),
} );
const subscriber = await res.json(); // res.status is 201 or 200

Can I react when the API adds someone?

Yes. A new subscriber fires do_action( 'mailpuff_contact_created', $contact_id, 'subscribe' ). Hook it from your own plugin to sync the person elsewhere. The hooks reference lists every hook Mailpuff fires.

FAQ

Not directly from the browser, because the key would be public. Post the form to a small server function, such as a serverless function, and call the API from there with the key in an environment variable.

The Subscribe API does one job with a key and no login. Mailpuff’s other REST routes under /wp-json/mailpuff/v1/ power the admin screens and need an administrator, for example signed in with an application password. For scripted access to everything else, the Mailpuff tools are the supported interface.

Can the API update a subscriber’s name?

No. For an existing address it only adds tags. Change names in Mailpuff → Subscribers.