Send a message

Send a message

Send a POST request to:

https://webapi.inboxroad.com/api/v1/messages

The request body must be sent as JSON.

Authentication is required. See Authentication.

Example request

curl -X POST 'https://webapi.inboxroad.com/api/v1/messages' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from_email": "sender@example.com",
    "from_name": "Example Sender",
    "to_email": "recipient@example.com",
    "to_name": "Example Recipient",
    "subject": "Hello from Inboxroad",
    "text": "Plain-text body",
    "html": "<h1>HTML body</h1>"
  }'

Request fields

Field name	Type	Required	Description
from_email	string	Yes	Valid email address the message is sent from.
from_name	string	No	Display name for the sender. Backslash (\) characters are not allowed.
to_email	string	Yes	Valid recipient email address.
to_name	string	No	Display name for the recipient. Backslash (\) characters are not allowed.
reply_to_email	string	No	Reply-To address. Defaults to from_email if omitted.
reply_to_name	string	No	Display name for the Reply-To address. Backslash (\) characters are not allowed.
subject	string	No	Subject line of the message.
text	string	Cond.	Plain-text body. Required if html is empty.
html	string	Cond.	HTML body. Required if text is empty.
headers	object	No	Extra email headers as a JSON object. Reserved headers are ignored.
attachments	array	No	List of attachment objects. See Attachment object.

Note

At least one of text or html must be provided.

If both are missing or empty, the request is rejected with 400.

Reserved headers

The following headers are managed by Inboxroad and are silently removed if you include them in headers:

Delivered-To, Return-Path, Content-Type, Subject, From, To, Reply-To, Message-ID.

Attachment object

Use the attachments field to include one or more files with your message.

Each attachment object must contain the following fields:

Field name	Type	Required	Description
filename	string	Yes	File name including extension.
mime_type	string	Yes	MIME type of the file, e.g. application/pdf.
file_data	string	Yes	Base64-encoded file contents. A data:...;base64, prefix is also accepted.

Caution

Executable and script file types are rejected for security reasons.

Examples include exe, bat, cmd, js, jar, msi, vbs, scr, and similar file types.

Full JSON example

{
  "from_email": "sender@example.com",
  "from_name": "Example Sender",
  "to_email": "recipient@example.com",
  "to_name": "Example Recipient",
  "reply_to_email": "reply@example.com",
  "reply_to_name": "Example Reply",
  "subject": "Hello from Inboxroad",
  "text": "Plain-text body",
  "html": "<h1>HTML body</h1>",
  "headers": {
    "X-Custom-Header": "value"
  },
  "attachments": [
    {
      "filename": "invoice.pdf",
      "mime_type": "application/pdf",
      "file_data": "JVBERi0xLjQKJ..."
    }
  ]
}

Response

When the message is sent successfully, the API returns 200 with the generated Message-ID.

You can use this Message-ID to match the message with later bounce and complaint events.

{
  "message_id": "<20260521094500.abc123@inboxroad.com>"
}

Code examples

Bash

curl -X POST 'https://webapi.inboxroad.com/api/v1/messages' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from_email": "sender@example.com",
    "from_name": "Example Sender",
    "to_email": "recipient@example.com",
    "subject": "Hello from Inboxroad",
    "text": "Plain-text body",
    "html": "<h1>HTML body</h1>"
  }'

Python

import requests

url = "https://webapi.inboxroad.com/api/v1/messages"
payload = {
    "from_email": "sender@example.com",
    "from_name": "Example Sender",
    "to_email": "recipient@example.com",
    "subject": "Hello from Inboxroad",
    "text": "Plain-text body",
    "html": "<h1>HTML body</h1>",
}
headers = {
    "X-API-Key": "<your_token>",
    "Content-Type": "application/json",
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

PHP

<?php
$ch = curl_init('https://webapi.inboxroad.com/api/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: <your_token>',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'from_email' => 'sender@example.com',
        'from_name' => 'Example Sender',
        'to_email' => 'recipient@example.com',
        'subject' => 'Hello from Inboxroad',
        'text' => 'Plain-text body',
        'html' => '<h1>HTML body</h1>',
    ]),
]);
echo curl_exec($ch);

Ruby

require "uri"
require "net/http"
require "json"

url = URI("https://webapi.inboxroad.com/api/v1/messages")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = "<your_token>"
request["Content-Type"] = "application/json"
request.body = {
  from_email: "sender@example.com",
  from_name: "Example Sender",
  to_email: "recipient@example.com",
  subject: "Hello from Inboxroad",
  text: "Plain-text body",
  html: "<h1>HTML body</h1>"
}.to_json

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

For interactive testing, visit the interactive API explorer.