Subscribe - Plugixa Easy Social Share Buttons for WordPress

POST /plugixa-social-share/v1/subscribe

Email a reader the post they are on and, if they ticked the box, add them to the site’s email list. This is what the “Save this post” form sends.

Needs Plugixa Easy Social Share Buttons Pro, with Save this post by email set up in Settings: either sending the post, or an email service, or both. Public: no login, no nonce and no Application Password. It is meant to be called from the visitor’s browser on a cached page.

Limited to five requests in ten minutes from one IP address, counted against a salted hash of it. The reader’s address is not stored on the site: it goes to the reader in the email and, only with consent, to the email service.

Note. A 200 does not always mean the email went out. When sending the post fails and the list was not asked for or not reached, the answer is still 200 and message says “Thank you. You’re on the list.” Treat message as text to show, not as a status.

Request

POST https://your-site.example/wp-json/plugixa-social-share/v1/subscribe

Request body

Content type: application/json

Field	Type	Required	Description
`email`	`string`	Yes	The reader’s email address.
`post`	`integer`	Yes	The ID of a published post, not password-protected, of a post type share buttons can be placed on.
`consent`	`boolean`	No	The reader ticked the box to join the list. Default `false`. Required when the form only subscribes and does not send the post.
`website`	`string`	No	A trap for bots: leave it out. When it has a value, the answer is a `200` and nothing is done.

{
  "email": "reader@example.com",
  "post": 123,
  "consent": true
}

Responses

`200` OK.

{
  "success": true,
  "data": {
    "message": "Done. Check your inbox for the post."
  }
}

Field	Type	Meaning
`data.message`	`string`	The sentence to show the reader, in the site’s language

message is one of: “Done. Check your inbox for the post.” (sent, and joined or not asked), “The post is on its way. We could not add you to the list just now; please try again later.” (sent, list not reached), or “Thank you. You’re on the list.” (otherwise).

Errors

Status	Code	When
`404`	`plugixa_social_share_not_found`	Share buttons are switched off, or the form is not set up.
`429`	`plugixa_social_share_too_many`	More than five requests in ten minutes from this address.
`400`	`plugixa_social_share_email`	`email` is not an email address. `data.field` is `email`.
`400`	`plugixa_social_share_post`	The post is missing, not published, password-protected, or of a type buttons are not placed on.
`400`	`plugixa_social_share_consent`	The form only subscribes and `consent` is not `true`. `data.field` is `consent`.
`502`	`plugixa_social_share_service`	The email service could not be reached and no post was sent.
`404`	`rest_no_route`	The free build, or the Save this post by email feature switched off.

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-social-share/v1/subscribe" \
  -H "Content-Type: application/json" \
  -d '{"email":"reader@example.com","post":123,"consent":true}'

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-social-share/v1/subscribe');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'email'   => 'reader@example.com',
        'post'    => 123,
        'consent' => true,
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://your-site.example/wp-json/plugixa-social-share/v1/subscribe', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: 'reader@example.com', post: 123, consent: true }),
});
const { data } = await response.json();