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.

If you turned on Approve transactional emails before sending in your settings, the status is awaiting_approval instead: the email is only sent once you approve it under Transactional emails. The same applies to emails sent over SMTP when approval is on for SMTP.

Examples

curl -X POST "https://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://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://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://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.

Send over SMTP

If your application, shop or CMS can only send email over SMTP, use the obanox SMTP server instead of the HTTP API. It uses the same API key and secret, the same verified sender domains and the same limits. Unlike the API, SMTP also supports attachments, Cc and Bcc.

The From address of each email must be on a verified sender domain. Every recipient (To, Cc and Bcc) counts as one email and appears as its own entry under Transactional emails. Bcc recipients stay hidden from the others.

The server answers with standard SMTP codes, so your application can tell a permanent error from a temporary one:

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. An email counts once, on the day it is accepted: also while it awaits your approval and if you reject it, but not again when you approve it later.

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. Blocks after an undeliverable email end on their own after 7 days. If an address was blocked by mistake (for example, the recipient has since fixed their mailbox), you can remove it under Suppressed emails in your account.

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.