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. Authentication

To use the API, include your API key in the HTTP Authorization header:

'Merchant-Id': 'MCH-3635939423',
'API-Key': 'sk_D7oW5tvG0RbaldrQIL5wHQxjQ98Wafxr0ugArCJ8QY',
'Authorization': 'Bearer '

All requests must be made over HTTPS.

3. API Endpoints

Send Email

Endpoint:

POST https://api.ozibus.com/v1/mail

Content-Type:

application/json

Description:

Submit a JSON payload to the queue and send an email. The email is processed on a per-recipient basis with individual status tracking.

4. JSON Payload Structure

Below is the complete JSON structure for an email request:

{
    "personalizations": [
        {
            "to": [
                {
                    "email": "[email protected]",
                    "name": "Recipient One"
                }
            ],
            "cc": [
                {
                    "email": "[email protected]",
                    "name": "CC Recipient"
                }
            ],
            "bcc": []
        },
        {
            "from": {
                "email": "[email protected]",
                "name": "Alternate Sender"
            },
            "to": [
                {
                    "email": "[email protected]",
                    "name": "Recipient Two"
                }
            ],
            "bcc": [
                {
                    "email": "[email protected]",
                    "name": "Audit Dept"
                }
            ]
        }
    ],
    "from": {
        "email": "[email protected]",
        "name": "Ozibus Messaging"
    },
    "reply_to": {
        "email": "[email protected]",
        "name": "Ozibus Support"
    },
    "subject": "Your Message Subject Here",
    "content": [
        {
            "type": "text/html",
            "value": "<;;h1>;;Welcome to Ozibus!<;;/h1>;;<;;p>;;Your email service is now active.<;;/p>;;"
        },
        {
            "type": "text/plain",
            "value": "Welcome to Ozibus! Your email service is now active."
        }
    ],
    "attachments": [
        {
            "content": "JVBERi0xLjQKJcfs... (base64 encoded content)",
            "filename": "document.pdf",
            "type": "application/pdf",
            "disposition": "attachment"
        }
    ],
    "settings": {
        "test_mode": {
            "enable": false
        }
    }
}

5. Field Descriptions

5.1 Personalizations

• to:
• An array of primary recipient objects.
• email (String, Required): recipient's email address.
• name (String, Optional): recipient's name.
• cc:
• (Optional) An array of CC recipient objects (same structure as "to").
• bcc:
• (Optional) An array of BCC recipient objects (same structure as "to").
• from:
• (Optional in a personalization object) Overrides the global sender details for this group.

5.2 Global Sender (from)

It defines the default sender information if no personalization overload is provided.

• email (String, Required)
• name (String, Optional)

5.3 Reply-To

Specifies the address for reply emails.

5.4 Subject

A string specifying the email's subject line.

5.5 Content

An array of objects containing the email body. It supports multiple formats (HTML and plain text).

• type (String): MIME type (e.g., "text/html").
• value (String): The email body content.

5.6 Attachments

(Optionally) Attach files to the email.

• content (String, Required): Base64-encoded file content.
• filename (String, Required): Name of the file.
• type (String, Required): MIME type (e.g., "application/pdf").
• disposition (String, Optional): "attachment" or "inline.".

5.7 Settings

Additional options:

• test_mode (Object): enable (Boolean): Set true to simulate sending without actual delivery.

6. Response Format

A typical response includes:

• response_code: Numeric code (0 for success, non-zero for errors).
• response_message: Description of the outcome.
• data: Additional data (e.g., queued IDs, transaction IDs).

Example Success Response:

{
  "response_code":0,
  "response_message":"Request processed and queue updated.",
  "data":{
          "error":[
                    {
                      "response_code":0,
                      "response_message":"Email sent successfully.",
                      "status":"sent",
                      "error":[]
                    }
                  ]
          }
}

Example Error Response:

{
  "response_code":20,
  "response_message":"At least one \"to\" email address is required.",
  "data":{
          "error":[]
         }
}

7. Error Codes

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

8. 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.

9. 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.

10. 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.