import { CommuneClient } from 'commune-ai';
const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });
const result = await commune.messages.send({
to: 'customer@example.com',
subject: 'Your order is confirmed',
html: '<p>Hi! Your order #12345 has been confirmed.</p>',
text: 'Hi! Your order #12345 has been confirmed.',
inboxId: 'inbox_abc123',
});
console.log(result.data.id); // resend message id
console.log(result.data.thread_id); // thread_abc123
from commune import CommuneClient
client = CommuneClient()
result = client.messages.send(
to="customer@example.com",
subject="Your order is confirmed",
html="<p>Hi! Your order #12345 has been confirmed.</p>",
text="Hi! Your order #12345 has been confirmed.",
inbox_id="inbox_abc123",
)
print(result.data.thread_id) # thread_abc123
send_email(
to="customer@example.com",
subject="Your order is confirmed",
body="Hi! Your order #12345 has been confirmed."
)
curl -X POST https://api.commune.email/v1/messages/send \
-H "Authorization: Bearer comm_..." \
-H "Content-Type: application/json" \
-d '{
"to": "customer@example.com",
"subject": "Your order is confirmed",
"html": "<p>Hi! Your order #12345 has been confirmed.</p>",
"text": "Hi! Your order #12345 has been confirmed.",
"inbox_id": "inbox_abc123"
}'
commune messages send \
--to "customer@example.com" \
--subject "Your order is confirmed" \
--body "Hi! Your order #12345 has been confirmed."
{
"data": {
"id": "49a3999c-0ce1-4ea6-ab68-e08a5c73e498",
"thread_id": "thread_f47ac10b-58cc-4372-a567-0e02b2c3d479",
"smtp_message_id": "<49a3999c-0ce1-4ea6-ab68-e08a5c73e498@resend.dev>"
}
}
{
"data": {
"id": "49a3999c-0ce1-4ea6-ab68-e08a5c73e498",
"thread_id": "thread_f47ac10b-58cc-4372-a567-0e02b2c3d479",
"smtp_message_id": "<49a3999c-0ce1-4ea6-ab68-e08a5c73e498@resend.dev>"
},
"validation": {
"warnings": ["role@example.com is a role address and may not deliver well"],
"suppressed": ["unsubscribed@example.com"],
"duration_ms": 142
}
}
{
"error": "validation_error",
"message": "subject is required"
}
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
Messages
Send email
Send an outbound email from one of your agent’s inboxes.
POST
/
v1
/
messages
/
send
import { CommuneClient } from 'commune-ai';
const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });
const result = await commune.messages.send({
to: 'customer@example.com',
subject: 'Your order is confirmed',
html: '<p>Hi! Your order #12345 has been confirmed.</p>',
text: 'Hi! Your order #12345 has been confirmed.',
inboxId: 'inbox_abc123',
});
console.log(result.data.id); // resend message id
console.log(result.data.thread_id); // thread_abc123
from commune import CommuneClient
client = CommuneClient()
result = client.messages.send(
to="customer@example.com",
subject="Your order is confirmed",
html="<p>Hi! Your order #12345 has been confirmed.</p>",
text="Hi! Your order #12345 has been confirmed.",
inbox_id="inbox_abc123",
)
print(result.data.thread_id) # thread_abc123
send_email(
to="customer@example.com",
subject="Your order is confirmed",
body="Hi! Your order #12345 has been confirmed."
)
curl -X POST https://api.commune.email/v1/messages/send \
-H "Authorization: Bearer comm_..." \
-H "Content-Type: application/json" \
-d '{
"to": "customer@example.com",
"subject": "Your order is confirmed",
"html": "<p>Hi! Your order #12345 has been confirmed.</p>",
"text": "Hi! Your order #12345 has been confirmed.",
"inbox_id": "inbox_abc123"
}'
commune messages send \
--to "customer@example.com" \
--subject "Your order is confirmed" \
--body "Hi! Your order #12345 has been confirmed."
{
"data": {
"id": "49a3999c-0ce1-4ea6-ab68-e08a5c73e498",
"thread_id": "thread_f47ac10b-58cc-4372-a567-0e02b2c3d479",
"smtp_message_id": "<49a3999c-0ce1-4ea6-ab68-e08a5c73e498@resend.dev>"
}
}
{
"data": {
"id": "49a3999c-0ce1-4ea6-ab68-e08a5c73e498",
"thread_id": "thread_f47ac10b-58cc-4372-a567-0e02b2c3d479",
"smtp_message_id": "<49a3999c-0ce1-4ea6-ab68-e08a5c73e498@resend.dev>"
},
"validation": {
"warnings": ["role@example.com is a role address and may not deliver well"],
"suppressed": ["unsubscribed@example.com"],
"duration_ms": 142
}
}
{
"error": "validation_error",
"message": "subject is required"
}
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
import { CommuneClient } from 'commune-ai';
const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });
const result = await commune.messages.send({
to: 'customer@example.com',
subject: 'Your order is confirmed',
html: '<p>Hi! Your order #12345 has been confirmed.</p>',
text: 'Hi! Your order #12345 has been confirmed.',
inboxId: 'inbox_abc123',
});
console.log(result.data.id); // resend message id
console.log(result.data.thread_id); // thread_abc123
from commune import CommuneClient
client = CommuneClient()
result = client.messages.send(
to="customer@example.com",
subject="Your order is confirmed",
html="<p>Hi! Your order #12345 has been confirmed.</p>",
text="Hi! Your order #12345 has been confirmed.",
inbox_id="inbox_abc123",
)
print(result.data.thread_id) # thread_abc123
send_email(
to="customer@example.com",
subject="Your order is confirmed",
body="Hi! Your order #12345 has been confirmed."
)
curl -X POST https://api.commune.email/v1/messages/send \
-H "Authorization: Bearer comm_..." \
-H "Content-Type: application/json" \
-d '{
"to": "customer@example.com",
"subject": "Your order is confirmed",
"html": "<p>Hi! Your order #12345 has been confirmed.</p>",
"text": "Hi! Your order #12345 has been confirmed.",
"inbox_id": "inbox_abc123"
}'
commune messages send \
--to "customer@example.com" \
--subject "Your order is confirmed" \
--body "Hi! Your order #12345 has been confirmed."
{
"data": {
"id": "49a3999c-0ce1-4ea6-ab68-e08a5c73e498",
"thread_id": "thread_f47ac10b-58cc-4372-a567-0e02b2c3d479",
"smtp_message_id": "<49a3999c-0ce1-4ea6-ab68-e08a5c73e498@resend.dev>"
}
}
{
"data": {
"id": "49a3999c-0ce1-4ea6-ab68-e08a5c73e498",
"thread_id": "thread_f47ac10b-58cc-4372-a567-0e02b2c3d479",
"smtp_message_id": "<49a3999c-0ce1-4ea6-ab68-e08a5c73e498@resend.dev>"
},
"validation": {
"warnings": ["role@example.com is a role address and may not deliver well"],
"suppressed": ["unsubscribed@example.com"],
"duration_ms": 142
}
}
{
"error": "validation_error",
"message": "subject is required"
}
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
Body
string | string[]
required
Recipient email address or array of recipient addresses. At least one recipient is required. Each address may be up to 320 characters.
string
required
Email subject line. Maximum 500 characters. CRLF characters are stripped automatically.
string
HTML body of the email. Maximum 10 MB. At least one of
html or text is required.string
Plain text fallback body. Maximum 10 MB. At least one of
html or text is required.string
Override the sender address. Must be a valid email address. When omitted, Commune resolves the sender from the
inbox_id or domain_id provided. If neither is given, the default sending address for your account is used.string
ID of the inbox to send from. Commune automatically resolves the
from address and domain from this inbox. Recommended over domain_id when you have per-agent inboxes.Accepts either inbox_id or inboxId.string
ID of the domain to send from when no
inbox_id is provided. Commune constructs the sender address using your account’s default local part and this domain.Accepts either domain_id or domainId.string
Existing thread to reply within. When set, Commune automatically sets
In-Reply-To and References headers so the message threads correctly in the recipient’s email client. The subject is also prefixed with Re: automatically.string | string[]
CC recipients. Accepts a single address or an array.
string | string[]
BCC recipients. Accepts a single address or an array.
string
Custom Reply-To address. When omitted, Commune sets a routing-token-encoded Reply-To automatically so inbound replies map back to the correct thread. Accepts either
reply_to or replyTo.string[] | object[]
Attachments to include with the email. Each element can be either an
attachment_id string (from the Upload attachment endpoint) or an inline attachment object.object
Custom email headers as a key-value map. Keys and values are sanitized (CRLF stripped). Standard headers like
Message-ID, In-Reply-To, and References are managed by Commune and will be overwritten.Response
object
Hide properties
Hide properties
string
The Resend message ID. This is the identifier your recipient’s email client will see. Format: UUID string.
string
Thread this message belongs to. If you supplied a
thread_id in the request, this echoes it back. Otherwise a new thread ID is generated. Format: thread_<uuid>.string
Full RFC 5322 Message-ID header value as seen by the recipient. Format:
<id@resend.dev>.object
Present only when some recipients were warned, rejected, or suppressed. A non-null
validation object does not mean the send failed — it means at least one recipient had an issue while others were sent successfully.Show properties
Show properties
string[]
Recipient addresses that failed hard validation (invalid syntax, no MX record) and were not sent to.
string[]
Addresses that passed but triggered soft warnings (role addresses, disposable domains). These recipients still received the email.
string[]
Addresses that are on your suppression list (bounced, unsubscribed). These recipients were silently skipped.
number
Time in milliseconds taken to validate all recipients.
Last modified on March 19, 2026
Was this page helpful?

