Send message

POST

mailboxes

{id}

messages

cURL

curl --request POST \
  --url https://app.getozi.com/api/v1/mailboxes/{id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": [
    "[email protected]"
  ],
  "subject": "Your invoice",
  "text": "<string>",
  "html": "<string>",
  "inline_images": [
    {
      "cid": "logo",
      "filename": "logo.png",
      "content_base64": "<string>"
    }
  ],
  "draft_id": "cm9msg123",
  "send_at": "2026-10-09T09:00:00Z"
}
'

import requests

url = "https://app.getozi.com/api/v1/mailboxes/{id}/messages"

payload = {
    "to": ["[email protected]"],
    "subject": "Your invoice",
    "text": "<string>",
    "html": "<string>",
    "inline_images": [
        {
            "cid": "logo",
            "filename": "logo.png",
            "content_base64": "<string>"
        }
    ],
    "draft_id": "cm9msg123",
    "send_at": "2026-10-09T09:00:00Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    to: ['[email protected]'],
    subject: 'Your invoice',
    text: '<string>',
    html: '<string>',
    inline_images: [{cid: 'logo', filename: 'logo.png', content_base64: '<string>'}],
    draft_id: 'cm9msg123',
    send_at: '2026-10-09T09:00:00Z'
  })
};

fetch('https://app.getozi.com/api/v1/mailboxes/{id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.getozi.com/api/v1/mailboxes/{id}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'to' => [
        '[email protected]'
    ],
    'subject' => 'Your invoice',
    'text' => '<string>',
    'html' => '<string>',
    'inline_images' => [
        [
                'cid' => 'logo',
                'filename' => 'logo.png',
                'content_base64' => '<string>'
        ]
    ],
    'draft_id' => 'cm9msg123',
    'send_at' => '2026-10-09T09:00:00Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.getozi.com/api/v1/mailboxes/{id}/messages"

	payload := strings.NewReader("{\n  \"to\": [\n    \"[email protected]\"\n  ],\n  \"subject\": \"Your invoice\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"inline_images\": [\n    {\n      \"cid\": \"logo\",\n      \"filename\": \"logo.png\",\n      \"content_base64\": \"<string>\"\n    }\n  ],\n  \"draft_id\": \"cm9msg123\",\n  \"send_at\": \"2026-10-09T09:00:00Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.getozi.com/api/v1/mailboxes/{id}/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"to\": [\n    \"[email protected]\"\n  ],\n  \"subject\": \"Your invoice\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"inline_images\": [\n    {\n      \"cid\": \"logo\",\n      \"filename\": \"logo.png\",\n      \"content_base64\": \"<string>\"\n    }\n  ],\n  \"draft_id\": \"cm9msg123\",\n  \"send_at\": \"2026-10-09T09:00:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.getozi.com/api/v1/mailboxes/{id}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"to\": [\n    \"[email protected]\"\n  ],\n  \"subject\": \"Your invoice\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"inline_images\": [\n    {\n      \"cid\": \"logo\",\n      \"filename\": \"logo.png\",\n      \"content_base64\": \"<string>\"\n    }\n  ],\n  \"draft_id\": \"cm9msg123\",\n  \"send_at\": \"2026-10-09T09:00:00Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "thread_id": "<string>",
  "sent_at": "2023-11-07T05:31:56Z",
  "scheduled": true,
  "scheduled_id": "<string>",
  "send_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_UNIQUE",
    "message": "<string>"
  }
}

Sends a new message from a mailbox to up to three addresses, in a conversation of its own. The message gets the mailbox’s signature, is filed in its Sent folder, counts against its storage and fires mailbox.message.sent. The response carries the new thread_id. Addresses must be bare ([email protected], no display name); they are trimmed, lower-cased and de-duplicated. The subject is one line of up to 200 characters: line breaks and other control characters are refused. The body can be plain text, formatted html with pictures in inline_images, or both, send_at holds it to send later, and draft_id names a draft of the same mailbox that it replaces (deleted once sent; anything that is not one of the mailbox’s drafts returns 404). See Formatted messages, pictures and scheduling for the rules. If any recipient is on your team’s suppression list, nothing is sent and the response is 400 with the code recipient_suppressed, naming the address. Remove it from the list, or leave it out, and send again. Send an Idempotency-Key header to retry safely: the same key with the same mailbox and body within 24 hours returns the first message instead of sending again, and the same key with a different body or mailbox returns 409 NOT_UNIQUE.

Needs an API key with full access.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

Same key and body within 24 hours returns the first message without sending again; same key with a different body, or on another mailbox, is 409 NOT_UNIQUE.

Required string length: 1 - 256

Path Parameters

string

required

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9_-]+$

Example:

"cm9mbx123"

Body

application/json

string[]

required

1-3 bare addresses ("[email protected]", no display name). They are trimmed, lower-cased and de-duplicated.

Required array length: 1 - 3 elements

Maximum string length: 254

Example:

["[email protected]"]

subject

string

required

One line, 1-200 characters, trimmed. Line breaks and other control characters are refused.

Maximum string length: 200

Example:

"Your invoice"

text

string

Plain-text body. The mailbox signature is appended when it has one. Required unless html is given, when it defaults to a plain-text copy of the html.

Required string length: 1 - 2097152

html

string

Formatted body. Cleaned on the server with the sanitizer webmail uses (scripts, forms, event handlers, blocks and unsafe links are dropped) before it is sent. The mailbox signature goes above an element with class "ozi_quote" when there is one, else at the end. When text is left out it is made from the html.

Required string length: 1 - 2097152

inline_images

object[]

Up to 10 pictures shown in the html by cid:, sent as inline attachments. Every cid: the html shows must be supplied, and every picture supplied must be shown.

Maximum array length: 10

Show child attributes

draft_id

string

A draft of the same mailbox this message replaces, such as the one a cancelled scheduled send became. It is deleted once the message is sent (or scheduled), as webmail does. Must be in the mailbox's Drafts folder, else 404.

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9_-]+$

Example:

"cm9msg123"

send_at

string<date-time>

RFC 3339 time to send at, from now to a year ahead. The message waits in the mailbox's Scheduled folder until then and can be cancelled, moved or sent now through /v1/scheduled/{id}. Use a few seconds ahead for an undo window.

Example:

"2026-10-09T09:00:00Z"

Response

Sends a new message (plain text, or formatted with inline pictures) from the mailbox in a thread of its own. The copy is stored in the mailbox's Sent folder (Scheduled while it waits, when send_at is given), gets the mailbox signature, counts against its quota and fires mailbox.message.sent when it goes.

string

required

thread_id

string

required

sent_at

string<date-time>

required

scheduled

boolean

required

True when the message waits to send (send_at was given). It is then in the Scheduled folder until it goes.

scheduled_id

string

When scheduled: the id to cancel, move or send now through /v1/scheduled/{id}. The same as id.

send_at

string<date-time>

When scheduled: when it will be sent.

cURL

curl --request POST \
  --url https://app.getozi.com/api/v1/mailboxes/{id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": [
    "[email protected]"
  ],
  "subject": "Your invoice",
  "text": "<string>",
  "html": "<string>",
  "inline_images": [
    {
      "cid": "logo",
      "filename": "logo.png",
      "content_base64": "<string>"
    }
  ],
  "draft_id": "cm9msg123",
  "send_at": "2026-10-09T09:00:00Z"
}
'

import requests

url = "https://app.getozi.com/api/v1/mailboxes/{id}/messages"

payload = {
    "to": ["[email protected]"],
    "subject": "Your invoice",
    "text": "<string>",
    "html": "<string>",
    "inline_images": [
        {
            "cid": "logo",
            "filename": "logo.png",
            "content_base64": "<string>"
        }
    ],
    "draft_id": "cm9msg123",
    "send_at": "2026-10-09T09:00:00Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    to: ['[email protected]'],
    subject: 'Your invoice',
    text: '<string>',
    html: '<string>',
    inline_images: [{cid: 'logo', filename: 'logo.png', content_base64: '<string>'}],
    draft_id: 'cm9msg123',
    send_at: '2026-10-09T09:00:00Z'
  })
};

fetch('https://app.getozi.com/api/v1/mailboxes/{id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.getozi.com/api/v1/mailboxes/{id}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'to' => [
        '[email protected]'
    ],
    'subject' => 'Your invoice',
    'text' => '<string>',
    'html' => '<string>',
    'inline_images' => [
        [
                'cid' => 'logo',
                'filename' => 'logo.png',
                'content_base64' => '<string>'
        ]
    ],
    'draft_id' => 'cm9msg123',
    'send_at' => '2026-10-09T09:00:00Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.getozi.com/api/v1/mailboxes/{id}/messages"

	payload := strings.NewReader("{\n  \"to\": [\n    \"[email protected]\"\n  ],\n  \"subject\": \"Your invoice\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"inline_images\": [\n    {\n      \"cid\": \"logo\",\n      \"filename\": \"logo.png\",\n      \"content_base64\": \"<string>\"\n    }\n  ],\n  \"draft_id\": \"cm9msg123\",\n  \"send_at\": \"2026-10-09T09:00:00Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.getozi.com/api/v1/mailboxes/{id}/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"to\": [\n    \"[email protected]\"\n  ],\n  \"subject\": \"Your invoice\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"inline_images\": [\n    {\n      \"cid\": \"logo\",\n      \"filename\": \"logo.png\",\n      \"content_base64\": \"<string>\"\n    }\n  ],\n  \"draft_id\": \"cm9msg123\",\n  \"send_at\": \"2026-10-09T09:00:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.getozi.com/api/v1/mailboxes/{id}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"to\": [\n    \"[email protected]\"\n  ],\n  \"subject\": \"Your invoice\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"inline_images\": [\n    {\n      \"cid\": \"logo\",\n      \"filename\": \"logo.png\",\n      \"content_base64\": \"<string>\"\n    }\n  ],\n  \"draft_id\": \"cm9msg123\",\n  \"send_at\": \"2026-10-09T09:00:00Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "thread_id": "<string>",
  "sent_at": "2023-11-07T05:31:56Z",
  "scheduled": true,
  "scheduled_id": "<string>",
  "send_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_UNIQUE",
    "message": "<string>"
  }
}

API Reference

Emails

Contact Books

Contacts

Domains

Campaigns

Analytics

Mailboxes

Send message

Authorizations

Headers

Path Parameters

Body

Response