> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commune.email/llms.txt
> Use this file to discover all available pages before exploring further.
# Send email
> Send an outbound email from one of your agent's inboxes.
```typescript TypeScript theme={null}
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: 'Hi! Your order #12345 has been confirmed.
',
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
```
```python Python theme={null}
from commune import CommuneClient
client = CommuneClient()
result = client.messages.send(
to="customer@example.com",
subject="Your order is confirmed",
html="Hi! Your order #12345 has been confirmed.
",
text="Hi! Your order #12345 has been confirmed.",
inbox_id="inbox_abc123",
)
print(result.data.thread_id) # thread_abc123
```
```bash MCP theme={null}
send_email(
to="customer@example.com",
subject="Your order is confirmed",
body="Hi! Your order #12345 has been confirmed."
)
```
```bash cURL theme={null}
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": "Hi! Your order #12345 has been confirmed.
",
"text": "Hi! Your order #12345 has been confirmed.",
"inbox_id": "inbox_abc123"
}'
```
```bash CLI theme={null}
commune messages send \
--to "customer@example.com" \
--subject "Your order is confirmed" \
--body "Hi! Your order #12345 has been confirmed."
```
```json 200 Success theme={null}
{
"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>"
}
}
```
```json 200 With validation warnings theme={null}
{
"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
}
}
```
```json 400 Bad Request theme={null}
{
"error": "validation_error",
"message": "subject is required"
}
```
```json 401 Unauthorized theme={null}
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
```
## Body
Recipient email address or array of recipient addresses. At least one recipient is required. Each address may be up to 320 characters.
Email subject line. Maximum 500 characters. CRLF characters are stripped automatically.
HTML body of the email. Maximum 10 MB. At least one of `html` or `text` is required.
Plain text fallback body. Maximum 10 MB. At least one of `html` or `text` is required.
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.
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`.
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`.
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.
CC recipients. Accepts a single address or an array.
BCC recipients. Accepts a single address or an array.
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`.
Attachments to include with the email. Each element can be either an `attachment_id` string (from the [Upload attachment](/api-reference/attachments/upload) endpoint) or an inline attachment object.
Filename shown to the recipient. CRLF characters are stripped.
Base64-encoded file content.
MIME type of the attachment (e.g. `application/pdf`).
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
The Resend message ID. This is the identifier your recipient's email client will see. Format: UUID 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_`.
Full RFC 5322 Message-ID header value as seen by the recipient. Format: ``.
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.
Recipient addresses that failed hard validation (invalid syntax, no MX record) and were not sent to.
Addresses that passed but triggered soft warnings (role addresses, disposable domains). These recipients still received the email.
Addresses that are on your suppression list (bounced, unsubscribed). These recipients were silently skipped.
Time in milliseconds taken to validate all recipients.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.