Transactional email API

Send single, personal emails from your own application through obanox: password resets, order confirmations, invoices, account notifications.

Each request sends one email to one recipient. Emails are queued and delivered within seconds. Addresses that bounce or report your mail as spam are blocked automatically, which protects your sender reputation.

Before you start

Send an email

Headers

Body fields

{
  "from": "[email protected]",
  "from_name": "Example Shop",
  "to": "[email protected]",
  "reply_to": "[email protected]",
  "subject": "Your order #10023",
  "html": "<p>Hello Max,</p><p>thank you for your order.</p>",
  "text": "Hello Max,\n\nthank you for your order."
}

The whole request may be at most 512 KB. We recommend sending both html and text: many mail programs and spam filters prefer messages with a plain-text version.

Response

202 Accepted: the email was accepted and queued for delivery.

{
  "id": 4711,
  "status": "queued"
}

Store the id if you want to reference the email when contacting support.

Examples

curl -X POST "https://www.obanox.com/api/v1/my-newsletter/send" \
  -H "Content-Type: application/json" \
  -H "API-KEY: your-api-key" \
  -H "API-SECRET: your-api-secret" \
  -d '{
    "from": "[email protected]",
    "from_name": "Example Shop",
    "to": "[email protected]",
    "reply_to": "[email protected]",
    "subject": "Your order #10023",
    "html": "<p>Hello Max,</p><p>thank you for your order.</p>",
    "text": "Hello Max,\n\nthank you for your order."
  }'

<?php
$payload = [
    'from'      => '[email protected]',
    'from_name' => 'Example Shop',
    'to'        => '[email protected]',
    'subject'   => 'Your order #10023',
    'html'      => '<p>Hello Max,</p><p>thank you for your order.</p>',
    'text'      => "Hello Max,\n\nthank you for your order.",
];

$ch = curl_init('https://www.obanox.com/api/v1/my-newsletter/send');
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 !== 202) {
    $error = json_decode($body, true)['error'] ?? $body;
    // handle the error, see "Errors"
}

const response = await fetch('https://www.obanox.com/api/v1/my-newsletter/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'API-KEY': process.env.OBANOX_API_KEY,
    'API-SECRET': process.env.OBANOX_API_SECRET,
  },
  body: JSON.stringify({
    from: '[email protected]',
    from_name: 'Example Shop',
    to: '[email protected]',
    subject: 'Your order #10023',
    html: '<p>Hello Max,</p><p>thank you for your order.</p>',
    text: 'Hello Max,\n\nthank you for your order.',
  }),
});

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

import os
import requests

response = requests.post(
    "https://www.obanox.com/api/v1/my-newsletter/send",
    headers={
        "API-KEY": os.environ["OBANOX_API_KEY"],
        "API-SECRET": os.environ["OBANOX_API_SECRET"],
    },
    json={
        "from": "[email protected]",
        "from_name": "Example Shop",
        "to": "[email protected]",
        "subject": "Your order #10023",
        "html": "<p>Hello Max,</p><p>thank you for your order.</p>",
        "text": "Hello Max,\n\nthank you for your order.",
    },
    timeout=10,
)

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

Errors

Errors return a JSON body with an error message:

{ "error": "The from address is not on a verified sender domain." }

Only retry on 429 (the next day) and 5xx. A 4xx error won't succeed by repeating the same request.

Delivery

• Asynchronous: 202 means the email was accepted, not yet delivered. It normally goes out within a few seconds.
• Temporary problems at the recipient's side (e.g. their mail server is briefly unavailable) are retried automatically. You don't need to resend.
• If an accepted email can't be sent on our side, it is kept and can be resent by obanox support. Don't send it again yourself, or the recipient may get it twice.
• Counted towards your plan: every transactional email counts towards your plan's daily email limit, together with your newsletter emails.

Bounces and spam complaints

To protect your sender reputation, obanox blocks addresses automatically:

This also covers your newsletter emails: an address that hard-bounced on a newsletter issue can't receive transactional emails from your account either.

A request to a blocked address returns 422 recipient_suppressed. If an address was blocked by mistake (for example, the recipient has since fixed their mailbox), contact obanox support to unblock it.

A high bounce or complaint rate can pause your newsletter's sending, which also stops the API (422 … sending is paused). Keep your rates low by only emailing addresses that recently gave them to you, and removing addresses that return recipient_suppressed.

Good practice

• One request per recipient. To email several people, send several requests.
• Use a dedicated sender address, e.g. [email protected] or [email protected], and set reply_to if recipients should be able to answer.
• Transactional emails only. Use this API for emails a recipient triggered or expects (account, order, security). Send marketing and newsletters through your newsletter, so recipients can unsubscribe.
• Avoid duplicate sends. If your request times out, you can't tell whether the email was accepted. Retrying may send it twice, so for critical emails log the request before retrying.

Limits

Support

Questions or an address to unblock? Contact obanox support and include the email id from the API response.