Email Delivery API

Welcome to the Ozibus Email Delivery API documentation. This guide is designed to help you seamlessly integrate with our robust email delivery service, whether you're building a new application or enhancing your existing system. In this documentation, you'll find detailed information on how to construct and format your JSON payloads, access our API endpoints, understand the various error codes you might encounter, and explore comprehensive usage examples.

Our goal is to provide you with a clear and practical resource that explains every aspect of the API—from the basic building blocks of request formation to advanced features such as multi-recipient processing, unit-based billing, and detailed status reporting. The Ozibus Email Delivery API is built with scalability and reliability in mind, ensuring that your messages are delivered promptly and securely, even in high-volume scenarios.

In this guide, you will learn:

Payload Structure: How to structure your JSON request, including fields for recipients, sender details, message content, attachments, and additional settings.
Endpoints: Detailed descriptions of our API endpoints, their purposes, and how to authenticate your requests.
Error Codes and Handling: A comprehensive list of error codes and best practices for handling errors to ensure smooth integration.
Usage Examples: Step-by-step examples and code snippets to help you quickly start sending emails through the Ozibus service.
Advanced Features: Guidance on leveraging multi-recipient support, managing attachments, configuring test modes, and more.

Whether you are integrating with a mobile app, a web platform, or a backend system, this documentation is your go-to resource for harnessing the full potential of the Ozibus Email Delivery API. We’ve designed our API to be developer-friendly, with clear instructions and best practices that make it easy to implement a reliable and efficient messaging solution.

Feel free to explore the sections below and refer back to this guide as you build, deploy, and manage your email delivery integration with Ozibus.

1. Overview

The Ozibus Email Delivery API enables you to send rich, multi-format emails to multiple recipients. The API supports:

Multiple recipient groups (To, CC, BCC)
Custom sender overrides per group
Attachments (base64-encoded)
Test mode and other advanced settings

This API is designed for high deliverability, reliability, and granular tracking for each recipient.

2. Error Codes

0: Success.
20: General failure (e.g., invalid payload, processing error).

3. Best Practices

Validate your payload on the client side to minimize errors.
Utilize test_mode during development to avoid unwanted live sends.
Monitor and log responses for auditing and troubleshooting.
Queue messages individually for better tracking and retry handling.
Secure your API with proper authentication and rate limiting.

4. Additional Information

For multi-recipient messages, Ozibus processes each recipient separately for better tracking and unit debit management. Each email is queued, and its status is updated based on the delivery outcome.

For more detailed integration and error-handling guidelines, please refer to our developer resources or contact support.

5. FAQ

Q: Can I send both HTML and plain text in one request?

A: Yes, include both formats in the content array.

Q: What happens if an attachment is too large?

A: Please ensure that attachments are within the size limits defined in your account settings. Oversized attachments may be rejected.

Q: How do I know if an email failed?

A: Our API response includes detailed error messages and status codes. Additionally, each email is tracked individually in our system.

This documentation should serve as a comprehensive guide for integrating with the Ozibus Emailing API. If you need further customizations or have additional questions, feel free to reach out to our developer support.

GET

/v1/mail

Request to /v1/mail

Headers

Name	Description	Required
Authorization	Bearer YOUR_API_KEY	Yes
API-Key	YOUR_API_KEY	Yes
Merchant-Id	YOUR_MERCHANT_ID	Yes
Content-Type	application/json	Yes

Request Body

Parameter	Type	Description	Required
personalizations	object		Yes
from	object	Sender phone number or alphanumeric ID	Yes
reply_to	object		Yes
subject	string		Yes
content	object		Yes
attachments	object		Yes
settings	object		Yes

Detected: curl

curl --location 'https://api.ozibus.com.au/v1/mail' \
--header 'Merchant-Id: <YOUR_MERCHANT_ID>' \
--header 'API-Key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--data-raw '{
  "personalizations": [
      {
          "to": [
              {
                  "email": "name@mail.com",
                  "name": "Name"
              }
              
          ],
          "cc": [
              
          ],
          "bcc": [
              
          ]
      },
      {
          "from": {
              "email": "",
              "name": ""
          },
          "to": [
              {
                  "email": "",
                  "name": ""
              }
          ],
          "bcc": [
              {
                  "email": "",
                  "name": ""
              }
          ]
      }
  ],
  "from": {
      "email": "noreply@ozibus.com.au",
      "name": "Company Name"
  },
  "reply_to": {
      "email": "email@company.com",
      "name": "Contact Name"
  },
  "subject": "Welcome",
  "content": [
      {
          "type": "text\\/html",
          "value": "<p>Message Body</p>"
      }
  ],
  "attachments": [
      {
          "content": "",
          "filename": "",
          "type": "",
          "disposition": ""
      }
  ],
  "settings": {
      "test_mode": {
          "enable": false
      }
  }
}'

Detected: curl

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.ozibus.com.au/v1/mail',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "personalizations": [
        {
            "to": [
                {
                    "email": "name@mail.com",
                    "name": "Name"
                }
                
            ],
            "cc": [
                
            ],
            "bcc": [
                
            ]
        },
        {
            "from": {
                "email": "",
                "name": ""
            },
            "to": [
                {
                    "email": "",
                    "name": ""
                }
            ],
            "bcc": [
                {
                    "email": "",
                    "name": ""
                }
            ]
        }
    ],
    "from": {
        "email": "noreply@ozibus.com.au",
        "name": "Company Name"
    },
    "reply_to": {
        "email": "email@company.com",
        "name": "Contact Name"
    },
    "subject": "Welcome",
    "content": [
        {
            "type": "text\\/html",
            "value": "<p>Message Body</p>"
        }
    ],
    "attachments": [
        {
            "content": "",
            "filename": "",
            "type": "",
            "disposition": ""
        }
    ],
    "settings": {
        "test_mode": {
            "enable": false
        }
    }
}
',
  CURLOPT_HTTPHEADER => array(
    'Merchant-Id: <YOUR_MERCHANT_ID>',
    'API-Key: <YOUR_API_KEY>',
    'Content-Type: application/json',
    'Authorization: Bearer <YOUR_JWT_TOKEN>'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Detected: php

<?php
$client = new Client();
$headers = [
  'Merchant-Id' => '<YOUR_MERCHANT_ID>',
  'API-Key' => '<YOUR_API_KEY>',
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer <YOUR_JWT_TOKEN>'
];
$body = '{
    "personalizations": [
        {
            "to": [
                {
                    "email": "",
                    "name": ""
                }
                
            ],
            "cc": [
                
            ],
            "bcc": [
                
            ]
        },
        {
            "from": {
                "email": "",
                "name": ""
            },
            "to": [
                {
                    "email": "",
                    "name": ""
                }
            ],
            "bcc": [
                {
                    "email": "",
                    "name": ""
                }
            ]
        }
    ],
    "from": {
        "email": "",
        "name": ""
    },
    "reply_to": {
        "email": "",
        "name": ""
    },
    "subject": "",
    "content": [
        {
            "type": "text\/html",
            "value": "message body"
        }
    ],
    "attachments": [
        {
            "content": "",
            "filename": "",
            "type": "",
            "disposition": ""
        }
    ],
    "settings": {
        "test_mode": {
            "enable": false
        }
    }
}
';
$request = new Request('POST', 'https://api.ozibus.com.au/v1/mail', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'api.ozibus.com.au',
  'path': '/v1/mail',
  'headers': {
    'Merchant-Id': '<YOUR_MERCHANT_ID>',
    'API-Key': '<YOUR_API_KEY>',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <YOUR_JWT_TOKEN>',
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "personalizations": [
      {
          "to": [
              {
                  "email": "name@mail.com",
                  "name": "Name"
              }
              
          ],
          "cc": [
              
          ],
          "bcc": [
              
          ]
      },
      {
          "from": {
              "email": "",
              "name": ""
          },
          "to": [
              {
                  "email": "",
                  "name": ""
              }
          ],
          "bcc": [
              {
                  "email": "",
                  "name": ""
              }
          ]
      }
  ],
  "from": {
      "email": "noreply@ozibus.com.au",
      "name": "Company Name"
  },
  "reply_to": {
      "email": "email@company.com",
      "name": "Contact Name"
  },
  "subject": "Welcome",
  "content": [
      {
          "type": "text\\/html",
          "value": "<p>Message Body</p>"
      }
  ],
  "attachments": [
      {
          "content": "",
          "filename": "",
          "type": "",
          "disposition": ""
      }
  ],
  "settings": {
      "test_mode": {
          "enable": false
      }
  }
});

req.write(postData);

req.end();

Detected: python

import requests
import json

url = "https://api.ozibus.com.au/v1/mail"

payload = json.dumps({
  "personalizations": [
      {
          "to": [
              {
                  "email": "name@mail.com",
                  "name": "Name"
              }
              
          ],
          "cc": [
              
          ],
          "bcc": [
              
          ]
      },
      {
          "from": {
              "email": "",
              "name": ""
          },
          "to": [
              {
                  "email": "",
                  "name": ""
              }
          ],
          "bcc": [
              {
                  "email": "",
                  "name": ""
              }
          ]
      }
  ],
  "from": {
      "email": "noreply@ozibus.com.au",
      "name": "Company Name"
  },
  "reply_to": {
      "email": "email@company.com",
      "name": "Contact Name"
  },
  "subject": "Welcome",
  "content": [
      {
          "type": "text\\/html",
          "value": "<p>Message Body</p>"
      }
  ],
  "attachments": [
      {
          "content": "",
          "filename": "",
          "type": "",
          "disposition": ""
      }
  ],
  "settings": {
      "test_mode": {
          "enable": false
      }
  }
})
headers = {
  'Merchant-Id': '<YOUR_MERCHANT_ID>',
  'API-Key': '<YOUR_API_KEY>',
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <YOUR_JWT_TOKEN>'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

API Documentation

Documentation