Subscriber API

Keep your newsletter's subscriber list in sync with your shop, CRM or signup forms: add and remove subscribers, and report bounces of mail you send yourself.

All endpoints are POST requests with a JSON body and the API-KEY / API-SECRET headers (see Authentication). Field names use camelCase, as in earlier versions of this API.

Add a subscriber

Body fields

curl -X POST "https://obanox.com/api/v1/my-newsletter/add-subscriber" \
  -H "Content-Type: application/json" \
  -H "API-KEY: your-api-key" \
  -H "API-SECRET: your-api-secret" \
  -d '{
    "email": "[email protected]",
    "firstName": "Max",
    "lastName": "Mustermann",
    "segments": ["Buyer", "Hamburg"]
  }'

<?php
$ch = curl_init('https://obanox.com/api/v1/my-newsletter/add-subscriber');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        'email'     => '[email protected]',
        'firstName' => 'Max',
        'segments'  => ['Buyer', 'Hamburg'],
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'API-KEY: ' . getenv('OBANOX_API_KEY'),
        'API-SECRET: ' . getenv('OBANOX_API_SECRET'),
    ],
]);
$result = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status >= 300) {
    // handle $result['error'], see "Errors"
}

const response = await fetch('https://obanox.com/api/v1/my-newsletter/add-subscriber', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'API-KEY': process.env.OBANOX_API_KEY,
    'API-SECRET': process.env.OBANOX_API_SECRET,
  },
  body: JSON.stringify({
    email: '[email protected]',
    firstName: 'Max',
    segments: ['Buyer', 'Hamburg'],
  }),
});
const result = await response.json();

import os
import requests

response = requests.post(
    "https://obanox.com/api/v1/my-newsletter/add-subscriber",
    headers={
        "API-KEY": os.environ["OBANOX_API_KEY"],
        "API-SECRET": os.environ["OBANOX_API_SECRET"],
    },
    json={
        "email": "[email protected]",
        "firstName": "Max",
        "segments": ["Buyer", "Hamburg"],
    },
    timeout=10,
)
result = response.json()

201 Created for a new subscriber, 200 OK when the address is already on the list ("created": false):

{
  "success": true,
  "message": "+ok",
  "id": 1341,
  "status": "pending",
  "created": true,
  "segments": ["Buyer", "Hamburg"]
}

segments lists the segments that were saved. Names that were not saved (too long, more than 5, or the list's limit of 100 segments reached) are listed in droppedSegments, which is only present then; the subscriber is added anyway.

Existing subscribers are not changed: name, birthday and segments stay as they are. status is one of active, pending (waiting for confirmation), unsubscribed, soft_bounce and hard_bounce.

Double opt-in

• Without isVerified (or false) the subscriber is pending and gets an email asking to confirm. Only after the click are they active and receive your posts (and your welcome email, if enabled).
• Adding a pending, unsubscribed or soft-bounced address again sends a new confirmation email (at most one every 10 minutes). Active and hard-bounced subscribers are left alone.
• With "isVerified": true you confirm that the person agreed to receive your newsletter, e.g. through your own double opt-in. They are active at once and no email is sent. An unsubscribed person is not re-subscribed this way, as long as they are still on the list. After remove-subscriber the address is gone, and adding it again counts as a new subscription.
• While your newsletter is paused or your account's email address isn't confirmed, new subscribers are still stored as pending. Their confirmation email is sent as soon as the newsletter can send again, if that happens within 7 days.

Remove a subscriber

Deletes the subscriber completely, including an unsubscribed or bounced status. Identify them by email or by unsubscribeKey (the key in their personal unsubscribe link); with both, both must match.

{ "email": "[email protected]" }

200 OK with "removed": true, or "removed": false when no such subscriber exists. Removing someone who isn't on the list is no error.

Report bounces

Mail sent through obanox is checked for bounces automatically. If you send to your subscribers through your own mail server, report its bounces here so obanox stops mailing those addresses.

{ "email": "[email protected]" }

All three return 200 OK with "updated": true when the status changed. Other cases are no error and return "updated": false: unknown addresses, and subscribers in another status. Pending subscribers stay pending (they haven't confirmed, so they get no posts to bounce) and unsubscribed ones stay unsubscribed.

Responses

For compatibility with earlier versions, every response has success (true / false) and a message. Errors additionally have error, like the other obanox APIs. Rely on the HTTP status code.

Errors

{
  "success": false,
  "message": "Missing required fields: email",
  "error": "Missing required fields: email"
}