Email Delivery API

Welcome to the Ozibus Email Delivery API documentation.

The Ozibus Email Delivery API enables applications, websites and backend systems to send secure, authenticated and trackable emails through the Ozibus communication platform.

Businesses with verified domains can send email using approved addresses from their own domains, such as:

accounts@yourcompany.com

support@yourcompany.com

notifications@yourcompany.com

Recipients see the authorised business sender address rather than an Ozibus-branded address, helping organisations maintain a consistent and trusted identity across transactional, operational and customer communication.

This guide explains how to integrate the Ozibus Email Delivery API into a new or existing application. It covers request construction, authentication, payload formatting, endpoints, recipient processing, attachments, testing, billing, status reporting and error handling.

The API is designed for scalability, reliability and granular message tracking. It can support individual messages as well as high-volume application workflows while processing each recipient independently for improved reporting, retry handling and usage calculation.

What you will learn

This documentation covers the following areas:

Payload structure

Learn how to construct a valid JSON request containing:

• To recipients

• CC recipients

• BCC recipients

• Sender details

• Reply-to details

• Subject

• HTML content

• Plain-text content

• Attachments

• Recipient groups

• Test-mode settings

• Additional delivery options

Authentication

Learn how to authenticate requests securely using your Ozibus API credentials.

API credentials should only be used from trusted server-side environments and must never be exposed in browser JavaScript, mobile application source code or public repositories.

API endpoints

Understand the available email-delivery endpoints, supported request methods and the purpose of each endpoint.

Verified-domain sending

Learn how approved sender addresses associated with verified business domains can be used in API requests.

For example:

From: Accounts Team <accounts@yourcompany.com>

The sender address must belong to a domain that has been verified and authorised within the associated Ozibus account.

Error codes and response handling

Review the available response codes, validation messages, and recommended error-handling practices.

Usage examples

Follow practical examples and code snippets for sending email from web applications, mobile backends, e-commerce systems, customer portals, and other software platforms.

Advanced features

Learn how to use capabilities such as the following:

• Multiple recipient groups

• Custom sender settings

• CC and BCC recipients

• HTML and plain-text content

• Base64-encoded attachments

• Test mode

• Recipient-level processing

• Unit-based billing

• Message queuing

• Delivery-status reporting

• Retry handling

1. Overview

The Ozibus Email Delivery API allows applications to send rich, multi-format email messages to one or more recipients.

It supports:

• To, CC, and BCC recipient groups

• HTML and plain-text message formats

• Verified-domain sender addresses

• Custom sender names

• Custom reply-to addresses

• Sender overrides where permitted

• Base64-encoded attachments

• Test mode

• Recipient-level message processing

• Delivery tracking

• Unit-based usage calculation

• Detailed API responses

• High-volume email workflows

The API can be used for communication such as the following:

• Account verification

• Password resets

• OTP and security codes

• Welcome emails

• Purchase confirmations

• Receipts

• Invoices

• Payment notifications

• Appointment reminders

• Booking confirmations

• Subscription updates

• Support notifications

• Delivery updates

• Customer onboarding

• Internal operational alerts

• Marketing and engagement campaigns

1.1 Verified-domain sender identity

Ozibus allows approved accounts to send authenticated email using addresses from their verified domains.

For example, a business that has verified

yourcompany.com

will be authorized to send from addresses such as

accounts@yourcompany.com
support@yourcompany.com
notifications@yourcompany.com

The sender details provided in an API request must comply with the domain and sender permissions configured in the Ozibus account.

Requests using an unverified domain or unauthorized sender address will be rejected.

Verified-domain sending helps businesses:

• Maintain a consistent sender identity

• Improve recipient trust

• Align messages with their corporate branding

• Separate transactional and marketing communication

• Manage approved senders centrally

• Support email authentication and signing requirements

1.2 Connected mailbox ecosystem

Ozibus also allows users to import or connect supported mailboxes belonging to their verified domains and access those mailboxes within the Ozibus workspace.

The Email Delivery API remains focused on programmatic outbound delivery. Connected mailbox access is a related Ozibus platform capability and may be managed separately through the Ozibus dashboard or other supported services.

This separation allows businesses to use Ozibus for both:

• Application-generated outbound email

• Centralised access to supported organisational mailboxes

Availability may depend on the account plan, mailbox provider, and enabled Ozibus services.

1.3 Recipient-level processing

When a request contains multiple recipients, Ozibus processes each recipient independently.

This provides:

• More accurate delivery tracking

• Separate status reporting

• Individual queue records

• Better retry handling

• Per-recipient failure visibility

• More accurate unit debiting

• Improved auditing

A single request containing several recipients may therefore generate multiple internal delivery records.

For example:

To: 2 recipients
CC: 1 recipient
BCC: 2 recipients

This may result in five separately processed recipient deliveries.

1.4 Unit-based billing

Email usage may be calculated according to the number of recipients processed rather than the number of API requests submitted.

For example, one request sent to five recipients may consume five email units.

Additional account rules may apply based on:

• Account plan

• Recipient count

• Attachment size

• Message type

• Enabled features

• Promotional or transactional classification

• Current Ozibus pricing

Applications should inspect API responses and account usage information rather than assuming that one request always represents one billable unit.

2. Request payload

The request payload is submitted as JSON.

Depending on the selected endpoint and account configuration, the payload may contain:

• Recipient information

• Sender information

• Reply-to information

• Message subject

• HTML content

• Plain-text content

• Attachments

• Delivery settings

• Test-mode options

• Tracking information

• Custom metadata

A typical request may include the following logical structure:

{
  "recipients": {
    "to": [],
    "cc": [],
    "bcc": []
  },
  "sender": {
    "email": "notifications@yourcompany.com",
    "name": "Your Company"
  },
  "reply_to": {
    "email": "support@yourcompany.com",
    "name": "Support Team"
  },
  "subject": "Your email subject",
  "content": {
    "html": "<p>Your HTML message</p>",
    "text": "Your plain-text message"
  },
  "attachments": [],
  "settings": {
    "test_mode": false
  }
}

The exact field names, accepted values, and required properties depend on the endpoint specification provided in the relevant section of this documentation.

2.1 Recipients

Recipients may be organized into the following:

• to

• cc

• bcc

Each recipient should contain a valid email address and may optionally include a display name.

Example:

{
  "email": "customer@example.com",
  "name": "Jane Smith"
}

Applications should validate recipient addresses before submitting the request.

2.2 Sender details

The sender object identifies the email address and display name shown to the recipient.

Example:

{
  "email": "accounts@yourcompany.com",
  "name": "Your Company Accounts"
}

The sender address must be authorized for the Ozibus account.

Where verified-domain restrictions apply, the address must belong to a domain that has been successfully verified and enabled for sending.

2.3 Reply-to details

The reply-to address determines where recipient replies should be delivered.

Example:

{
  "email": "support@yourcompany.com",
  "name": "Your Company Support"
}

The reply-to address may differ from the sending address where permitted.

This is useful when an application is sent from:

notifications@yourcompany.com

But replies should be directed to:

support@yourcompany.com

2.4 Message content

The API may support both HTML and plain-text content in the same request.

Providing both formats is recommended.

Example:

{
  "html": "<h1>Welcome</h1><p>Thank you for joining us.</p>",
  "text": "Welcome\n\nThank you for joining us."
}

The receiving email client can choose the most appropriate format.

HTML content should be:

• Valid

• Responsive where possible

• Free from unsafe scripts

• Suitable for common email clients

• Tested before live delivery

Plain-text content should remain readable without HTML formatting.

2.5 Attachments

Attachments may be submitted as base64-encoded content.

A typical attachment object may include:

• File name

• MIME type

• Base64-encoded file content

Example structure:

{
  "filename": "invoice.pdf",
  "mime_type": "application/pdf",
  "content": "BASE64_ENCODED_FILE_CONTENT"
}

Attachment limits may depend on:

• File size

• Total request size

• File type

• Account configuration

• Security restrictions

Oversized or unsupported attachments may cause the request or affected message to be rejected.

Applications should validate attachments before encoding and submitting them.

3. Authentication

All API requests must be authenticated using valid Ozibus credentials.

The required authentication method may include an API key, a bearer token, or another credential specified for the endpoint.

Credentials should be:

• Stored securely

• Loaded from environment variables

• Restricted to server-side applications

• Rotated when necessary

• Revoked immediately if exposed

• Separated between development and production environments

Do not place Ozibus API credentials directly in the following:

• Public JavaScript

• HTML source code

• Mobile application packages

• Public repositories

• Client-accessible configuration files

• Error messages

• Application logs

Example environment configuration:

OZIBUS_API_URL=https://api.example.com
OZIBUS_API_KEY=your-secure-api-key
OZIBUS_SENDER_EMAIL=notifications@yourcompany.com
OZIBUS_SENDER_NAME="Your Company"

Use the actual API URL and credentials supplied through your Ozibus account.

4. API endpoints

Each endpoint section should specify:

• Endpoint URL

• HTTP method

• Authentication requirements

• Required headers

• Required fields

• Optional fields

• Request example

• Success response

• Error responses

• Rate limits

• Billing behaviour

A typical request uses:

POST /mail
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

The exact endpoint path and authentication header must match the current Ozibus API specification.

5. API responses

The API response should be checked after every request.

A successful submission may indicate that the message has been

• Accepted

• Validated

• Queued

• Scheduled

• Processed

A successful API response does not always mean that the recipient’s mail server has completed final delivery.

Applications should distinguish between:

• Request acceptance

• Message queuing

• Delivery attempt

• Successful delivery

• Temporary failure

• Permanent failure

• Rejection

• Bounce

• Complaint

Where available, delivery records, dashboard activity, or webhooks should be used to determine the final delivery outcome.

6. Error codes

Code 0 — Success

The request was accepted and processed successfully according to the returned status information.

A success response should still be logged with its message or recipient identifiers for later tracking.

Code 20 — General failure

A general failure may indicate:

• Invalid JSON

• Missing required fields

• Invalid recipient data

• Invalid sender details

• Unverified sender domain

• Unauthorised sender address

• Unsupported attachment

• Oversized attachment

• Insufficient account units

• Authentication failure

• Internal processing error

• Queue failure

The accompanying error message should be reviewed for the specific cause.

Additional error codes may be introduced or documented separately as the API evolves.

Applications should not rely exclusively on the numeric code. They should also inspect:

• HTTP status

• Response status

• Error message

• Validation details

• Recipient-level results

• Message identifiers

7. Error-handling recommendations

Applications integrating with Ozibus should:

• Validate all required fields before sending

• Validate email-address formats

• Confirm that sender addresses are authorised

• Confirm that sending domains are verified

• Check attachment sizes before encoding

• Handle network timeouts

• Log request identifiers

• Log recipient-level results

• Retry temporary failures

• Avoid retrying permanent validation errors

• Prevent duplicate sends

• Use idempotency controls where supported

• Alert administrators after repeated failures

• Protect sensitive data in logs

Retries should use controlled backoff rather than repeatedly submitting failed requests immediately.

For example:

Attempt 1: immediately
Attempt 2: after 1 minute
Attempt 3: after 5 minutes
Attempt 4: after 15 minutes

The exact retry policy should match the application’s urgency and the type of failure returned.

8. Test mode

Use test mode while developing or validating your integration.

Test mode can help confirm:

• Authentication

• Payload formatting

• Required fields

• Sender permissions

• Recipient parsing

• Attachment processing

• Template rendering

• API response handling

• Application logging

Example:

{
  "settings": {
    "test_mode": true
  }
}

The exact behavior of test mode may depend on the endpoint and account configuration.

Before enabling live delivery:

• Verify the sending domain

• Confirm approved sender addresses

• Review message content

• Test HTML and plain-text versions

• Validate links

• Validate reply-to settings

• Test attachments

• Confirm recipient handling

• Confirm usage and billing behaviour

• Disable test mode explicitly

9. Best practices

Validate requests before submission

Perform client-side or server-side validation before calling the API.

Validation should include:

• Required fields

• Email-address formats

• Valid sender details

• Content availability

• Attachment limits

• Recipient counts

• Supported data types

Use verified sender identities

Only use approved sender addresses associated with domains that have been verified in the Ozibus account.

Provide HTML and plain text

Where supported, include both HTML and plain-text versions to improve compatibility and accessibility.

Use a monitored reply-to address

Do not direct replies to an unmonitored address unless replies are intentionally disabled.

Keep transactional and marketing communication separate

Use appropriate sender identities, templates, and recipient preferences for each category.

Respect recipient consent

Only send promotional communication to recipients who have provided the required consent.

Monitor API responses

Store message identifiers, recipient results, and status information for auditing and support.

Queue messages in your application

For high-volume workflows, submit emails through an application queue rather than blocking user-facing requests.

Handle recipients independently

Because Ozibus processes recipients separately, your application should be prepared to receive mixed results within a multi-recipient operation.

For example:

Recipient A: accepted
Recipient B: invalid address
Recipient C: queued

Protect API credentials

Use environment variables or a secure secrets-management solution.

Prevent duplicate delivery

Generate a unique internal reference for each business event, such as:

• Order ID

• Invoice ID

• User-verification ID

• Booking ID

• Notification ID

Record whether the corresponding email has already been sent.

Use appropriate rate limiting

Apply rate limiting to public workflows such as:

• Password resets

• OTP requests

• Contact forms

• Invitation emails

• Resend-verification actions

10. High-volume delivery

The Ozibus Email Delivery API is designed to support scalable email workflows.

For high-volume use:

• Use background queues

• Split large workloads into manageable batches

• Monitor account units

• Track each recipient independently

• Apply retry policies

• Avoid duplicate submissions

• Monitor failure rates

• Review domain reputation

• Keep recipient data current

• Remove invalid or repeatedly bouncing addresses

• Respect unsubscribe and preference settings

A high-volume request should not be treated as one indivisible operation. Recipient-level processing allows Ozibus to record and manage each delivery separately.

11. Delivery tracking and status reporting

Where supported, each processed recipient receives an individual delivery record.

Status information may include:

• Accepted

• Queued

• Processing

• Sent

• Delivered

• Deferred

• Failed

• Rejected

• Bounced

• Complained

• Cancelled

Applications should store the Ozibus message identifier or recipient identifier returned by the API.

These identifiers can be used for:

• Troubleshooting

• Customer support

• Auditing

• Retry management

• Usage reconciliation

• Delivery reporting

• Webhook processing

A message being marked as sent does not always mean it has reached the recipient’s inbox. It may indicate that the message was successfully handed to the next delivery stage.

12. Recommended integration flow

A typical integration should follow this process:

1. The application generates an email event.

2. The request data is validated.

3. The application creates a unique internal reference.

4. The email is placed in an application queue.

5. A background worker submits the request to Ozibus.

6. Ozibus validates the sender, recipients and content.

7. Ozibus processes each recipient separately.

8. The API returns message and recipient results.

9. The application stores the response.

10. Delivery status is monitored through available reports or webhooks.

11. Temporary failures are retried according to policy.

12. Permanent failures are logged and reviewed.

13. Frequently asked questions

Can I send both HTML and plain-text content in one request?

Yes. Where supported by the endpoint, include both versions in the message content.

Providing both formats is recommended because some email clients or recipient preferences may favour plain text.

Can I send from my business email address?

Yes, provided the domain has been verified and the sender address has been approved for the Ozibus account.

For example:

accounts@yourcompany.com

Recipients will see the configured business sender identity rather than an Ozibus-branded sender address.

Can I use different sender addresses?

Yes, where those addresses belong to verified domains and are authorised for the account.

Unauthorised sender addresses may be rejected.

Can I specify a different reply-to address?

Yes, where supported. This allows messages to be sent from one approved address while directing replies to another monitored mailbox.

Can I send to To, CC and BCC recipients?

Yes. The API supports multiple recipient groups, subject to the endpoint specification and account limits.

How are multiple recipients processed?

Ozibus processes each recipient separately for improved tracking, status reporting, retry handling and unit calculation.

Does one API request always consume one email unit?

Not necessarily. Usage may be calculated according to the number of recipients processed.

A request containing multiple recipients may consume multiple units.

What happens when an attachment is too large?

Oversized attachments may cause the message or request to be rejected.

Check the attachment limits configured for your account before submitting the request.

How do I know whether an email failed?

Review the API response, recipient-level status and available delivery records.

Where supported, delivery webhooks or dashboard activity can provide additional status updates after the initial API response.

Does a successful API response mean the email has reached the inbox?

Not always.

A successful response may mean the request was accepted or queued. Final delivery depends on later processing and the receiving mail server.

Should I use test mode during development?

Yes. Test mode should be used while validating payloads, authentication, sender configuration and application logic.

Can Ozibus access existing business mailboxes?

Ozibus may support importing or connecting mailboxes belonging to verified domains. This is a related platform capability and is separate from the outbound Email Delivery API.

Can I expose the API key in my frontend application?

No.

API credentials must be stored and used only in a trusted server-side environment.

14. Developer support

This documentation is intended to provide a practical foundation for integrating the Ozibus Email Delivery API.

Before requesting support, collect the following information:

• Request date and time

• Endpoint used

• HTTP status

• Ozibus response code

• Error message

• Message identifier

• Recipient identifier

• Internal application reference

• Whether test mode was enabled

Do not send API keys, passwords or other secrets in support messages.

For additional assistance, consult the latest Ozibus developer resources or contact Ozibus developer support

Conclusion

The Ozibus Email Delivery API provides a secure and scalable way to integrate custom-domain email delivery into websites, mobile backends, customer platforms and business applications.

With verified-domain sender identities, multiple recipient groups, HTML and plain-text content, attachments, test mode, recipient-level processing, unit-based usage and detailed status reporting, the API can support both simple notifications and complex high-volume communication workflows.

Use the sections that follow to configure authentication, construct your request payloads, review endpoint requirements and begin sending authenticated business email through Ozibus.