Sending a message

Sending a message

To send a message, make a POST request with a JSON payload to:

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

Authenticate with your API token — see v1 authentication.

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 (see below).
attachments	array	No	List of attachment objects (see below).

Note

At least one of text or html must be provided, otherwise the request is rejected with 400.

Reserved headers

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

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

Attachment object

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 (e.g. exe, bat, cmd, js, jar, msi, vbs, scr, and similar).

Example request

{
  "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

On success the API returns 200 with the generated Message-ID, which you can use to correlate later bounce and complaint events.

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

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.