Posts API

Publish newsletter posts from your CMS, blog or automation: create a post, then send it to your subscribers right away or at a time you choose.

A post created through the API is the same as one written in the editor: it appears under Posts in your account, where you can still edit, reschedule or cancel it until sending starts. Posts are written in the name of the newsletter's owner.

Before you start

Create a post

Headers

Body fields

Without send or send_at the post is saved as a draft, to be reviewed and sent in your account. Use either send or send_at, not both.

{
  "subject": "Our November update",
  "subtitle": "New features and three tips for the holidays",
  "html": "<p>Hello,</p><p>here is what is new this month …</p>",
  "template_id": 12,
  "send_at": "2026-11-02T09:00:00+01:00"
}

Response

201 Created: the post was saved, and scheduled if you asked to send it.

{
  "id": 4711,
  "status": "scheduled",
  "slug": "our-november-update",
  "use_template": true,
  "template_id": 12,
  "send_after": "2026-11-02T09:00:00+01:00"
}

Examples

curl -X POST "https://obanox.com/api/v1/my-newsletter/posts" \
  -H "Content-Type: application/json" \
  -H "API-KEY: your-api-key" \
  -H "API-SECRET: your-api-secret" \
  -d '{
    "subject": "Our November update",
    "html": "<p>Here is what is new this month …</p>",
    "send": true
  }'

<?php
$payload = [
    'subject' => 'Our November update',
    'html'    => '<p>Here is what is new this month …</p>',
    'send'    => true,
];

$ch = curl_init('https://obanox.com/api/v1/my-newsletter/posts');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'API-KEY: ' . getenv('OBANOX_API_KEY'),
        'API-SECRET: ' . getenv('OBANOX_API_SECRET'),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 201) {
    $error = json_decode($body, true)['error'] ?? $body;
    // handle the error, see "Errors"
}

const response = await fetch('https://obanox.com/api/v1/my-newsletter/posts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'API-KEY': process.env.OBANOX_API_KEY,
    'API-SECRET': process.env.OBANOX_API_SECRET,
  },
  body: JSON.stringify({
    subject: 'Our November update',
    html: '<p>Here is what is new this month …</p>',
    send: true,
  }),
});

if (response.status !== 201) {
  const { error } = await response.json();
  // handle the error, see "Errors"
}

import os
import requests

response = requests.post(
    "https://obanox.com/api/v1/my-newsletter/posts",
    headers={
        "API-KEY": os.environ["OBANOX_API_KEY"],
        "API-SECRET": os.environ["OBANOX_API_SECRET"],
    },
    json={
        "subject": "Our November update",
        "html": "<p>Here is what is new this month …</p>",
        "send": True,
    },
    timeout=10,
)

if response.status_code != 201:
    error = response.json().get("error")
    # handle the error, see "Errors"

Check a post

Same headers as above, without a body. Returns the post's current state:

{
  "id": 4711,
  "status": "sent",
  "subject": "Our November update",
  "slug": "our-november-update",
  "use_template": true,
  "template_id": 12,
  "send_after": "2026-11-02T09:00:00+01:00",
  "published_at": "2026-11-02T09:00:12+01:00",
  "total_recipients": 1250,
  "total_sent": 1250,
  "send_error": null,
  "url": "https://my-newsletter.obanox.com/our-november-update"
}

• send_error: why the post could not be sent yet, e.g. a limit of your plan; null otherwise. Fix the cause in your account; the post is sent once it can be.
• url: the post on your newsletter website, once sending started and if web_visible is on; null otherwise.

Templates

Every post is sent in a template: an HTML design with your header, footer and unsubscribe link. Templates are created in your account under Templates, where you can also choose the default for new posts. Without one of your own, posts use the built-in layout with your logo and accent color.

Lists your newsletter's templates. Use an id as template_id when creating a post.

[
  { "id": 12, "name": "Monthly update", "default": true },
  { "id": 15, "name": "Short announcement", "default": false }
]

Your own design

If your website already builds the complete email, send it with "use_template": false. The html is then sent exactly as you send it: a full HTML document with <head>, <style> and inline styles. Only <script> blocks are removed.

• Required: an unsubscribe link with the placeholder {{ unsubscribe_url }}, e.g. <a href="{{ unsubscribe_url }}">Unsubscribe</a>. It is replaced with each subscriber's personal link.
• Placeholders work as in templates: {{ first_name }}, {{ last_name }}, {{ email }}, {{ web_url }} (view in browser), {{ newsletter_name }}, {{ newsletter_imprint }} and more.
• Tracking (if enabled for your newsletter) works as usual: links are tracked and an open pixel is added.
• On your newsletter website the post is shown in the website's design: only the content of <body> is used, while head, title, styles and anything unsafe are removed. The post subject is the page heading, so headings in your html move down one level (<h1> becomes <h2>; <h6> stays <h6>), and the first <h1> is left out if it repeats the subject. Hidden elements such as a preheader (display:none) are not shown.
• Such posts can be previewed, test-sent and cancelled in your account, but not edited in the post editor.

{
  "subject": "Our November update",
  "use_template": false,
  "html": "<!doctype html><html><head><style>h1 { color: #e4572e; }</style></head><body><h1>Hello {{first_name}}</h1><p>…</p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></body></html>",
  "send": true
}

Errors

Errors return a JSON body with an error message. When a post can't be sent, problems lists every reason:

{
  "error": "The post cannot be sent.",
  "problems": [
    "Please enter your imprint in the settings first."
  ]
}

Good practice

• Avoid duplicate posts. Each successful request creates a new post. If a request times out, check under Posts in your account before retrying, or the post may be sent twice.
• Draft first when unsure. Leave out send and send_at to review the post in your account and send a test email before it goes out.
• Host your images. Reference images by their https URL in the HTML.

Limits

Support

Questions? Contact obanox support and include the post id from the API response.