Send transactional email for user domain with optional attachments

POST

/api/domains/{domain}/message

Application server

Send a transactional email for a specific domain owned by the authenticated user. This endpoint is designed for user-authenticated requests where the user owns and manages the domain. Supports comprehensive email customization, bulk sending, file attachments with advanced processing, and asynchronous job handling for optimal performance. Perfect for building custom email solutions and transactional workflows.

Authorizations

basicAuth

Parameters

Path Parameters

domain

required

string

Example

example.com

Domain name that must be owned by the authenticated user. This domain must be verified and configured with SMTP credentials.

Request Body^required

Complete email configuration including content, recipients, and optional attachments with processing options.

object

from

required

Sender email address. Must belong to the authenticated domain. Used for envelope sender and Return-Path header.

string format: email

Example

[email protected]

from_name

Optional sender display name. If not provided, will use the email address only.

string

Example

Company Name

required

One of:

string
Array<string>

string format: email

Example

[email protected]

Array<string>

<= 1000 items

Example

[
  "[email protected]",
  "[email protected]",
  "[email protected]"
]

subject

required

Email subject line. Supports Unicode characters, emojis, and variable content. Keep under 78 characters for optimal display across email clients.

string

Example

Your Order Confirmation - #12345

text

required

Required plain text content for the email body. This will be used as fallback for email clients that don’t support HTML. Line breaks will be preserved.

string

Example

Dear Valued Customer,\n\nThank you for your recent order #12345. Your items are being prepared for shipment.\n\nOrder Details:\n- Product: Premium Widget\n- Quantity: 2\n- Total: $49.99\n\nTracking information will be sent once your order ships.\n\nBest regards,\nCustomer Service Team

html

Optional HTML content for the email body. If provided, this will be used for HTML email clients. Should be a complete HTML document or HTML fragment.

string

Example

<html><body><h2>Order Confirmation - #12345</h2><p>Dear Valued Customer,</p><p>Thank you for your recent order #12345. Your items are being prepared for shipment.</p><h3>Order Details:</h3><ul><li>Product: Premium Widget</li><li>Quantity: 2</li><li>Total: $49.99</li></ul><p>Tracking information will be sent once your order ships.</p><p>Best regards,<br>Customer Service Team</p></body></html>

headers

One of:

object
string

object

Example

{
  "X-Order-ID": "12345",
  "X-Customer-Tier": "premium",
  "X-Tags": "newsletter,promo",
  "List-Unsubscribe": "mailto:[email protected]",
  "X-Priority": "3"
}

string

Example

{"X-Order-ID": "12345", "X-Customer-Tier": "premium", "X-Tags": "newsletter,promo"}

reply_to

Reply-to email address. Must share the same top-level domain as the ‘from’ address for security compliance.

string format: email

Example

[email protected]

attachments

One of:

string
Array<string>

Single file attachment

string format: binary

attachment_options

Advanced attachment processing configuration as JSON string. Enables compression, password protection, and watermarking features.

string

Example

{"compress": true, "password": "SecureDoc2024", "watermark": {"enabled": true, "text": "CONFIDENTIAL", "position": "center"}}

Responses

202

Email send jobs successfully dispatched for asynchronous processing

object

success

Request processing success status

boolean

Example

true

message

Detailed success message including recipient count, job batching information, and attachment count

string

Example

Email send jobs dispatched for 5 recipients in 1 job(s) with 2 attachment(s)

Headers

X-RateLimit-Limit

integer

Maximum requests per minute

X-RateLimit-Remaining

integer

Remaining requests in current window

400

Bad Request - Missing authentication or invalid request structure

object

error

string

Example

User authentication missing

401

Unauthorized - Invalid user credentials or session expired

object

error

string

Example

Authentication required

404

Domain not found or user does not own the specified domain

object

error

string

Example

Domain not found or you do not own this domain.

422

Validation Error - Invalid input data, business rule violations, or configuration issues

object

One of:

object
object

object

success

boolean

message

string

Example

Validation failed.

errors

object

error

string

Example

Total email payload exceeds maximum size

429

Too Many Requests - Rate limit exceeded. Retry after the specified time.

object

success

boolean

message

string

Example

Too many attempts. Please try again later.

Headers

Retry-After

integer

Seconds until rate limit resets

X-RateLimit-Limit

integer

Maximum requests per minute

X-RateLimit-Remaining

integer

Remaining requests in current window

500

Internal Server Error - Unexpected system error during processing

object

success

boolean

message

string

Example

An error occurred while sending the message. Please try again.

Send transactional email for user domain with optional attachments

Authorizations

Parameters

Path Parameters

Example

Request Body required

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

202

Example

Example

Headers

400

Example

401

Example

404

Example

422

Example

Example

429

Example

Headers

500

Example

Request Body^required