Skip to main content

Transmission API

The Transmission API is the canonical endpoint for sending transactional and bulk email through Mailtarget. This page is the developer-facing wrapper around the OpenAPI-generated reference. The auto-generated schema with field-level definitions, examples, and try-it-out is in the API Reference section once gen:api runs.

Endpoint​

POST https://transmission.mailtarget.co/v1/layang/transmissions

Authentication: bearer token. See Authentication.

Required fields​

FieldTypeDescription
subjectstringThe subject line.
fromobjectSender identity. Must contain email. May contain name. The domain in email must be a verified sending domain on the account.
toarray of objectsPrimary recipients. Each item contains email and optionally name. At least one recipient is required.

Optional fields​

FieldTypeDescription
replyToobject or arrayAddress that receives replies.
ccarray of objectsCarbon-copy recipients.
bccarray of objectsBlind carbon-copy recipients.
bodyTextstringPlain-text body. Recommended for every send for clients that block HTML.
bodyHtmlstringHTML body.
headersobjectCustom headers as key-value pairs. Reserved headers (From, To, Subject, Date, Message-ID) are managed by the platform and ignored if you set them.
attachmentsarrayFile attachments. Each attachment is an object with name, type (MIME type), and data (base64-encoded content).
metadataobjectFree-form key-value metadata that echoes into webhook events. Use this to carry your own correlation IDs (order ID, user ID, campaign code).
optionsAttributesobjectPer-message options (open tracking, click tracking, sandbox mode, scheduled send time).
templateIdstringIdentifier of a server-side template. When set, bodyHtml and bodyText are taken from the template.
substitutionDataobjectPer-recipient or global substitution variables consumed by the template engine.
allRCPTtobooleanWhen true, all addresses in to, cc, and bcc see all other addresses in the headers. Default behavior treats each to recipient as a separate envelope.

Response​

A successful submit returns:

{ "transmissionId": "string" }

Persist the transmissionId. It is the join key for Webhooks.

Error response​

{
  "error":   "stable_error_code",
  "message": "human-readable description"
}

The error catalog and retry guidance are in Errors and Rate Limits.

Example: minimum viable send​

curl https://transmission.mailtarget.co/v1/layang/transmissions \
  -X POST \
  -H "Authorization: Bearer $MAILTARGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Hello",
    "from":    { "email": "you@your-verified-domain.com" },
    "to":      [ { "email": "user@example.com" } ],
    "bodyText": "Hello"
  }'

Example: server-side template with substitution data​

curl https://transmission.mailtarget.co/v1/layang/transmissions \
  -X POST \
  -H "Authorization: Bearer $MAILTARGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject":    "Receipt for order #{{order_id}}",
    "templateId": "tmpl_receipt_v3",
    "from":       { "email": "billing@your-verified-domain.com", "name": "Your Company" },
    "to":         [ { "email": "user@example.com" } ],
    "substitutionData": {
      "order_id":  "10042",
      "amount":    "Rp 250.000",
      "ship_date": "2026-05-10"
    },
    "metadata": {
      "order_id": "10042",
      "user_id":  "u_abc"
    }
  }'

Example: attachment​

ATTACHMENT_B64=$(base64 -i invoice.pdf)

curl https://transmission.mailtarget.co/v1/layang/transmissions \
  -X POST \
  -H "Authorization: Bearer $MAILTARGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"subject\": \"Your invoice\",
    \"from\":    { \"email\": \"billing@your-verified-domain.com\" },
    \"to\":      [ { \"email\": \"user@example.com\" } ],
    \"bodyText\": \"Invoice attached.\",
    \"attachments\": [
      { \"name\": \"invoice.pdf\", \"type\": \"application/pdf\", \"data\": \"$ATTACHMENT_B64\" }
    ]
  }"