Send transactional email for user domain with optional attachments

POST

/api/domains/{domain}/message

const url = 'https://smtp-app.kirim.email/api/domains/example.com/message';
const form = new FormData();
form.append('from', '[email protected]');
form.append('from_name', 'Company Name');
form.append('to', '[email protected]');
form.append('subject', 'Your Order Confirmation - #12345');
form.append('text', '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');
form.append('html', '<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>');
form.append('headers', '{ "X-Order-ID": "12345", "X-Customer-Tier": "premium", "X-Tags": "newsletter,promo", "List-Unsubscribe": "mailto:[email protected]", "X-Priority": "3" }');
form.append('reply_to', '[email protected]');
form.append('attachments', 'binary');
form.append('attachment_options', '{"compress": true, "password": "SecureDoc2024", "watermark": {"enabled": true, "text": "CONFIDENTIAL", "position": "center"}}');

const options = {method: 'POST', headers: {Authorization: 'Basic <credentials>'}};

options.body = form;

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://smtp-app.kirim.email/api/domains/example.com/message \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: multipart/form-data' \
  --form [email protected] \
  --form 'from_name=Company Name' \
  --form [email protected] \
  --form 'subject=Your Order Confirmation - #12345' \
  --form 'text=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' \
  --form 'html=<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>' \
  --form 'headers={ "X-Order-ID": "12345", "X-Customer-Tier": "premium", "X-Tags": "newsletter,promo", "List-Unsubscribe": "mailto:[email protected]", "X-Priority": "3" }' \
  --form [email protected] \
  --form attachments=binary \
  --form 'attachment_options={"compress": true, "password": "SecureDoc2024", "watermark": {"enabled": true, "text": "CONFIDENTIAL", "position": "center"}}'

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.

multipart/form-data

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

application/json

object

success

Request processing success status

boolean

message

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

string

Example

{
  "success": true,
  "message": "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

application/json

object

error

string

Example

{
  "error": "User authentication missing"
}

401

Unauthorized - Invalid user credentials or session expired

application/json

object

error

string

Example

{
  "error": "Authentication required"
}

404

Domain not found or user does not own the specified domain

application/json

object

error

string

Example

{
  "error": "Domain not found or you do not own this domain."
}

422

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

application/json

object

One of:

object
object

object

success

boolean

message

string

errors

object

Example

{
  "": {
    "success": false,
    "message": "Validation failed."
  }
}

429

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

application/json

object

success

boolean

message

string

Example

{
  "success": false,
  "message": "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

application/json

object

success

boolean

message

string

Example

{
  "success": false,
  "message": "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 Bodyrequired

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

202

Example

Headers

400

Example

401

Example

404

Example

422

Example

429

Example

Headers

500

Example

Request Body^required