Send transactional email for user domain using a saved template

POST

/api/domains/{domain}/message/template

curl --request POST \
  --url https://smtp-app.kirim.email/api/domains/example.com/message/template \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: multipart/form-data' \
  --form template_guid=550e8400-e29b-41d4-a716-446655440000 \
  --form [email protected] \
  --form [email protected] \
  --form 'from_name=Company Name' \
  --form 'variables={ "name": "John Doe", "product": "Premium Widget" }' \
  --form 'headers={ "X-Campaign-ID": "welcome-series" }' \
  --form [email protected] \
  --form attachments=binary \
  --form 'attachment_options={"compress": true, "password": "secret123", "watermark": {"enabled": true, "text": "CONFIDENTIAL"}}'

• Application server

Send an email for a domain owned by the authenticated user using a stored template. Supports variable replacement using {{variable}} syntax in both subject and content. Template must belong to the authenticated domain. Supports attachments with the same processing options as non-template message endpoint.

Authorizations

• basicAuth

Parameters

Path Parameters

domain

required

string

Example

example.com

Domain name that must be owned by the authenticated user

Request Body^required

Media typemultipart/form-data

object

template_guid

required

UUID of the template to use

string format: uuid

Example

550e8400-e29b-41d4-a716-446655440000

to

required

One of:

string

string format: email

Example

[email protected]

Array<string>

Array<string>

<= 1000 items

Example

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

from

Sender email address. Must belong to the authenticated domain. Defaults to noreply@{domain} if not provided.

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

variables

One of:

object

Single set of variables for all recipients

object

Example

{
  "name": "John Doe",
  "product": "Premium Widget"
}

Array<object>

Array of variable objects, one per recipient

Array<object>

object

Example

[
  {
    "name": "John",
    "product": "Widget A"
  },
  {
    "name": "Jane",
    "product": "Widget B"
  }
]

headers

One of:

object

object

Example

{
  "X-Campaign-ID": "welcome-series"
}

string

string

Example

{"X-Campaign-ID": "welcome-series"}

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

Single file attachment

string format: binary

Array<string>

Multiple file attachments

Array<string>

<= 10 items

attachment_options

JSON string with attachment processing options. Watermark text is limited to 50 characters.

string

Example

{"compress": true, "password": "secret123", "watermark": {"enabled": true, "text": "CONFIDENTIAL"}}

Responses

202

Template-based email jobs dispatched

Media typeapplication/json

object

success

boolean

message

string

template_guid

string

template_name

string

Example

{
  "success": true,
  "message": "Template-based email jobs dispatched for 2 recipients in 1 job(s)",
  "template_guid": "550e8400-e29b-41d4-a716-446655440000",
  "template_name": "Welcome Email"
}

Headers

X-RateLimit-Limit

integer

Maximum requests per minute

X-RateLimit-Remaining

integer

Remaining requests in current window

401

Unauthorized - Invalid or missing authentication credentials

Media typeapplication/json

object

success

boolean

message

string

Example

{
  "success": false,
  "message": "Unauthorized"
}

404

Not Found - Domain or template not found

Media typeapplication/json

object

success

boolean

message

string

Example

{
  "success": false,
  "message": "Domain not found or you do not own this domain."
}

422

Validation Error - Invalid input data

Media typeapplication/json

object

success

boolean

message

string

errors

Field-specific validation errors

object

Example

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

429

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

Media typeapplication/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

Server Error - Unexpected error occurred

Media typeapplication/json

object

success

boolean

message

string

Example

{
  "success": false,
  "message": "An error occurred while sending the template message. Please try again."
}