Send transactional messages in a batchMenu

Send transactional messages in a batch

POST/v1/transactional/messages/batch

Requires an API key with the transactional:send scope. About keys and scopes

Works with integration and partner keys, not agent keys.

Each entry carries its own idempotencyKey; a retried entry replays. About idempotency

Sends up to 100 transactional messages in one request. Each entry of messages holds a single send (see POST /v1/transactional/messages) as its message, optionally with its own idempotencyKey, and gets its own result: results keeps the order of messages, each with its messages (one per channel the entry sends on) and replayed, or the error a single send would have returned. One refused entry does not stop the rest. The call counts against the rate limit as one request per entry.

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Request body

messagesobject[]required

at least 1 item · at most 100 items

2 child attributes

idempotencyKeystringoptional

As the Idempotency-Key header of a single send: one per message you mean. Without one, a retried batch sends this message again.

8–255 characters

messageSendTransactionalInputrequired

8 child attributes

toobjectrequired

Who receives it.

Any of 3 shapes

By contact id

1 child attribute

contactIdstringrequired

An existing contact.

uuid

By external id

1 child attribute

externalIdstringrequired

Your own id for an existing contact, as set with identify.

1–255 characters

By email

1 child attribute

emailstringrequired

The recipient's address. An email send to an address no contact has creates a transactional-only contact; a push-only send needs an existing contact.

email · up to 320 characters

datamap<string, any>optional

Values the content reads as {{ data.<key> }}: a stored template, inline email and the push title and body alike.

keys: pattern ^[A-Za-z0-9_-]{1,64}$

sensitivebooleanoptional

Set when the message carries a secret (a reset link, a one-time code): its content is kept only while the message is queued or sending, and removed once sending finishes, whatever the workspace's retention says.

correlationIdstringoptional

Your own reference for this send, echoed on its webhooks and its read.

1–255 characters

emailobjectoptional

Inline (subject, from, html), or a stored template by template; either may carry attachments, threading, tracking, cc and bcc.

Any of 2 shapes

Stored template

10 child attributes

templatestringrequired

The template's alias, such as password-reset, or its id.

subjectstringoptional

The subject line. Merge tags are allowed.

1–998 characters

previewTextstringoptional

Shown by inboxes after the subject. Merge tags are allowed; keep it near 100 characters.

1–255 characters

fromstringoptional

The sender address, on a verified sending domain.

1–320 characters

replyTostringoptional

Where replies go; the part before the @ must be ASCII.

attachmentsEmailAttachmentInput[]optional

Files it carries: up to 10, 10 MB in all.

at least 1 item · at most 10 items

threadingEmailThreadingInputoptional

Places it in an existing conversation, as the In-Reply-To and References headers.

trackingTransactionalEmailTrackingInputoptional

Open and click tracking; off unless asked for. Contacts whose country is in the EEA or the UK are never tracked.

ccstring[]optional

Addresses that get a copy and are shown in its Cc line. Each goes as its own message, with its own bounces and complaints, and counts as one email. Up to 14 across cc and bcc.

at least 1 item · at most 14 items

bccstring[]optional

Addresses that get a copy without being shown to anyone. Sent and counted as cc is.

at least 1 item · at most 14 items

Inline content

12 child attributes

subjectstringrequired

The subject line. Merge tags are allowed.

1–998 characters

previewTextstringoptional

Shown by inboxes after the subject. Merge tags are allowed; keep it near 100 characters.

1–255 characters

htmlstringrequired

The HTML body. Rendered from the design when one is set.

1–512,000 characters

textstringoptional

The plain-text alternative.

1–512,000 characters

fromstringrequired

The sender address, on a verified sending domain.

1–320 characters

replyTostringoptional

Where replies go; the part before the @ must be ASCII.

attachmentsEmailAttachmentInput[]optional

Files it carries: up to 10, 10 MB in all.

at least 1 item · at most 10 items

threadingEmailThreadingInputoptional

Places it in an existing conversation, as the In-Reply-To and References headers.

trackingTransactionalEmailTrackingInputoptional

Open and click tracking; off unless asked for. Contacts whose country is in the EEA or the UK are never tracked.

ccstring[]optional

Addresses that get a copy and are shown in its Cc line. Each goes as its own message, with its own bounces and complaints, and counts as one email. Up to 14 across cc and bcc.

at least 1 item · at most 14 items

bccstring[]optional

Addresses that get a copy without being shown to anyone. Sent and counted as cc is.

at least 1 item · at most 14 items

mergeTagsbooleanoptional

Set to false for HTML that is already finished: {{ then goes out exactly as written, and nothing is checked or filled in. {{unsubscribe_url}} and {{web_version_url}} still work. Defaults to true.

pushTransactionalPushInputoptional

A push notification to the contact's devices. Give push, email, or both.

14 child attributes

titlestringrequired

The notification title (up to 100 characters).

1–100 characters

bodystringrequired

The notification text (up to 500 characters).

1–500 characters

actionUrlstringoptional

The HTTPS page opened when the notification is tapped.

uri · up to 2,048 characters

imageUrlstringoptional

A large picture: web and Android show it; iOS needs the app's service extension.

uri · up to 2,048 characters

iconUrlstringoptional

Web only; iOS and Android show the app's own notification icon.

uri · up to 2,048 characters

datamap<string, string>optional

Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.

at most 10 keys · keys: pattern ^[A-Za-z0-9_.-]{1,64}$ · values: up to 1,024 characters

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

2 child attributes

titlestringrequired

The button label.

1–30 characters

urlstringrequired

The HTTPS page the button opens.

uri · up to 2,048 characters

collapseKeystringoptional

A newer notification with the same key replaces the older one on the device.

pattern ^[A-Za-z0-9_-]{1,64}$

soundstringoptional

The name of a sound the app ships; the device's default if unset.

1–64 characters

badgeintegeroptional

The number shown on the iOS app icon.

min 0 · max 99999

ttlDurationOrZeroInputoptional

How long a provider keeps trying an offline device, up to 28 days; zero delivers now or never. Defaults to one day.

2 child attributes

valueintegerrequired: min 0
unitstringrequired: one of seconds, minutes, hours, days

urgencystringoptional

high asks the push service to deliver promptly, even to a sleeping device; normal lets it wait for a good moment to save battery. Device settings and the app still decide whether and how it is shown. Unset, a transactional push is high and any other normal.

one of high, normal

overridesobjectoptional

Fields that differ on one platform, each replacing the shared one there (a whole data map, not merged key by key). On iOS and Android actionUrl may be an app link such as myapp://orders; the shared one and the web one must be HTTPS.

3 child attributes

iosobjectoptional: Replaces shared fields on iOS.
androidobjectoptional: Replaces shared fields on Android.
webobjectoptional: Replaces shared fields on web.

pushProjectIdstringoptional

Reaches the contact's devices on every app of the project. Needed only when the workspace has more than one push project.

uuid

sendAtstringoptional

When to send, up to 90 days ahead, with its UTC offset. Suppression and push reachability are checked when the request is accepted and again when it goes. A fallbackOrder fallback keeps this time but goes only after the message before it fails, is skipped or bounces.

date-time

fallbackOrderstring[]optional

With both push and email, each once, in the order to try them: the first the contact can receive is sent, and the next only if it fails, is skipped or bounces. Left out, each channel the contact can receive is sent.

at least 1 item

Returns

Returns 202 Accepted with a SendTransactionalMessagesBatchResult in data. It can also return 409 Conflict, 413 Payload Too Large or 415 Unsupported Media Type; see the statuses below. Otherwise returns an error; Errors lists every code and which to retry.

202 AcceptedOne result per entry, in order.
409 ConflictThe request conflicts with current state — a duplicate unique value, or a resource whose status does not allow this operation.
413 Payload Too LargeThe body is larger than this operation accepts (PAYLOAD_TOO_LARGE).
415 Unsupported Media TypeThe body is not JSON, or not the upload the operation takes (UNSUPPORTED_MEDIA_TYPE).

resultsobject[]required

Any of 2 shapes

Accepted

5 child attributes

idempotencyKeystring | nullrequired

As sent; null when none was.

replayedbooleanrequired

True when this key had already been accepted; nothing new was sent.

messagesTransactionalMessage[]required

8 child attributes

idstringrequired

uuid

channelstringrequired

one of email, push

statusstringrequired

one of queued, sending, skipped, sent, failed, delivered, bounced, complained

correlationIdstring | nullrequired

The correlationId given when it was sent, if any.

createdAtstringrequired

date-time

sendAtstring | nullrequired

When a timed message goes out; null when it went at once.

date-time

fallbackForstring | nullrequired

With fallbackOrder: the message this one stands in for. It waits as queued until that one ends: sent when it failed, was skipped or bounced, else skipped with reason fallback_not_needed. Null otherwise.

uuid

copyobject | nullrequired

Set on a cc or bcc copy; null on the message itself.

2 child attributes

kindstringrequired

one of cc, bcc

ofstringrequired

The message it is a copy of.

uuid

skippedChannelsTransactionalSkippedChannel[]required

Channels given that were not sent, each with the reason: the contact cannot receive it, or the plan has no room for it.

3 child attributes

channelstringrequired: one of email, push
codestringrequired: Its error code, such as SUPPRESSED.
messagestringrequired

skippedCopiesTransactionalSkippedCopy[]required

cc or bcc addresses that got no copy, each with the reason.

4 child attributes

emailstringrequired
kindstringrequired: one of cc, bcc
codestringrequired: Its error code, such as SUPPRESSED.
messagestringrequired

Rejected

2 child attributes

idempotencyKeystring | nullrequired

errorobjectrequired

5 child attributes

codestringrequired

one of BAD_REQUEST, ALREADY_EXISTS, CONFLICT, IN_USE, FORBIDDEN, SCOPE_MISSING, AGENT_KEY_REFUSED, INTERNAL_ERROR, NOT_FOUND, METHOD_NOT_ALLOWED, PAYLOAD_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE, RATE_LIMITED, REVISION_CONFLICT, SERVICE_UNAVAILABLE, UNAUTHORIZED, VALIDATION_ERROR, API_KEY_IP_NOT_ALLOWED, AGENT_CONFIRMATION_REQUIRED, EMBED_BUILDER_UNAVAILABLE, EMBED_ORIGIN_NOT_ALLOWED, WORKSPACE_SUSPENDED, WORKSPACE_DELETION_PENDING, CONTACT_SEND_IN_PROGRESS, EXPORT_UNAVAILABLE, NOTHING_TO_EXPORT, EVENT_NAME_LIMIT_REACHED, PLAN_LIMIT_REACHED, SENDING_REVIEW_REQUIRED, PLAN_FEATURE_UNAVAILABLE, CAMPAIGN_AUDIENCE_CONFLICT, EMPTY_AUDIENCE, DRAFT_INCOMPLETE, INVALID_SCHEDULE, UNSUPPORTED_CHANNEL, POSTAL_ADDRESS_MISSING, CONSENT_MISSING, SUPPRESSED, TOPIC_UNSUBSCRIBED, SIGNUP_BLOCKED, INVALID_SENDER_ADDRESS, SENDING_DOMAIN_DMARC_MISSING, SENDING_DOMAIN_IDENTITY_CONFLICT, TEST_SEND_OUTCOME_UNKNOWN, TEST_SEND_ROUTE_NOT_READY, TEST_SEND_UNAVAILABLE, SENDING_DOMAIN_UNVERIFIED, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_KEY_IN_USE, IDEMPOTENCY_KEY_OUTCOME_UNKNOWN, CONTENT_NOT_RETAINED, RECIPIENT_EMAIL_MISSING, RECIPIENT_EMAIL_UNSUPPORTED, TEMPLATE_NOT_PUBLISHED, TEMPLATE_ENVELOPE_INCOMPLETE, PUSH_APP_NOT_READY, PUSH_DESTINATION_MISSING, FORM_CLOSED

messagestringrequired

errorsFieldError[]optional

Each field the request got wrong: on VALIDATION_ERROR and DRAFT_INCOMPLETE.

6 child attributes

instringoptional

The part of the request the field is in, when known.

one of body, query, params, headers

fieldstringrequired

Dotted path to the field (blocks.0.text); empty for the whole part.

codestringoptional

The rule that failed (too_big, invalid_type, custom, …).

messagestringrequired

Plain words, meant to be shown beside the field.

minimumnumberoptional

The bound a too_small rule set.

maximumnumberoptional

The bound a too_big rule set.

detailsobjectoptional

What else the error carries, by code: see that code's description.

requestIdstringoptional

curl -X POST https://api.kirora.io/v1/transactional/messages/batch \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "idempotencyKey": "order-1001-receipt",
        "message": {
          "to": {
            "externalId": "customer-4821"
          },
          "correlationId": "order-1001",
          "data": {
            "order_id": "1001",
            "total": "$45.00",
            "item_count": 3
          },
          "email": {
            "template": "order-receipt"
          }
        }
      },
      {
        "idempotencyKey": "order-1002-receipt",
        "message": {
          "to": {
            "externalId": "customer-5307"
          },
          "correlationId": "order-1002",
          "data": {
            "order_id": "1002",
            "total": "$18.50",
            "item_count": 1
          },
          "email": {
            "template": "order-receipt"
          }
        }
      }
    ]
  }'

const response = await fetch('https://api.kirora.io/v1/transactional/messages/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messages": [
      {
        "idempotencyKey": "order-1001-receipt",
        "message": {
          "to": {
            "externalId": "customer-4821"
          },
          "correlationId": "order-1001",
          "data": {
            "order_id": "1001",
            "total": "$45.00",
            "item_count": 3
          },
          "email": {
            "template": "order-receipt"
          }
        }
      },
      {
        "idempotencyKey": "order-1002-receipt",
        "message": {
          "to": {
            "externalId": "customer-5307"
          },
          "correlationId": "order-1002",
          "data": {
            "order_id": "1002",
            "total": "$18.50",
            "item_count": 1
          },
          "email": {
            "template": "order-receipt"
          }
        }
      }
    ]
  }),
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/transactional/messages/batch",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "messages": [
            {
                "idempotencyKey": "order-1001-receipt",
                "message": {
                    "to": {
                        "externalId": "customer-4821",
                    },
                    "correlationId": "order-1001",
                    "data": {
                        "order_id": "1001",
                        "total": "$45.00",
                        "item_count": 3,
                    },
                    "email": {
                        "template": "order-receipt",
                    },
                },
            },
            {
                "idempotencyKey": "order-1002-receipt",
                "message": {
                    "to": {
                        "externalId": "customer-5307",
                    },
                    "correlationId": "order-1002",
                    "data": {
                        "order_id": "1002",
                        "total": "$18.50",
                        "item_count": 1,
                    },
                    "email": {
                        "template": "order-receipt",
                    },
                },
            },
        ],
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "messages": [
	    {
	      "idempotencyKey": "order-1001-receipt",
	      "message": {
	        "to": {
	          "externalId": "customer-4821"
	        },
	        "correlationId": "order-1001",
	        "data": {
	          "order_id": "1001",
	          "total": "$45.00",
	          "item_count": 3
	        },
	        "email": {
	          "template": "order-receipt"
	        }
	      }
	    },
	    {
	      "idempotencyKey": "order-1002-receipt",
	      "message": {
	        "to": {
	          "externalId": "customer-5307"
	        },
	        "correlationId": "order-1002",
	        "data": {
	          "order_id": "1002",
	          "total": "$18.50",
	          "item_count": 1
	        },
	        "email": {
	          "template": "order-receipt"
	        }
	      }
	    }
	  ]
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/transactional/messages/batch", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.kirora.io/v1/transactional/messages/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));
request.Content = new StringContent(
    """
    {
      "messages": [
        {
          "idempotencyKey": "order-1001-receipt",
          "message": {
            "to": {
              "externalId": "customer-4821"
            },
            "correlationId": "order-1001",
            "data": {
              "order_id": "1001",
              "total": "$45.00",
              "item_count": 3
            },
            "email": {
              "template": "order-receipt"
            }
          }
        },
        {
          "idempotencyKey": "order-1002-receipt",
          "message": {
            "to": {
              "externalId": "customer-5307"
            },
            "correlationId": "order-1002",
            "data": {
              "order_id": "1002",
              "total": "$18.50",
              "item_count": 1
            },
            "email": {
              "template": "order-receipt"
            }
          }
        }
      ]
    }
    """,
    Encoding.UTF8,
    "application/json");

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 202

{
  "data": {
    "results": [
      {
        "idempotencyKey": "order-1001-receipt",
        "replayed": false,
        "messages": [
          {
            "id": "0192f3b0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
            "channel": "email",
            "status": "queued",
            "correlationId": "order-1001",
            "createdAt": "2026-11-17T08:30:00.000Z",
            "sendAt": null,
            "fallbackFor": null,
            "copy": null
          }
        ],
        "skippedChannels": [],
        "skippedCopies": []
      },
      {
        "idempotencyKey": "order-1002-receipt",
        "replayed": false,
        "messages": [
          {
            "id": "0192f3b0-3c4d-7e5f-8a61-7c8d9e0f1a2b",
            "channel": "email",
            "status": "queued",
            "correlationId": "order-1002",
            "createdAt": "2026-11-17T08:30:00.000Z",
            "sendAt": null,
            "fallbackFor": null,
            "copy": null
          }
        ],
        "skippedChannels": [],
        "skippedCopies": []
      }
    ]
  }
}

curl -X POST https://api.kirora.io/v1/transactional/messages/batch \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "idempotencyKey": "order-1003-receipt",
        "message": {
          "to": {
            "externalId": "customer-4821"
          },
          "correlationId": "order-1003",
          "data": {
            "order_id": "1003",
            "total": "$24.00",
            "item_count": 2
          },
          "email": {
            "template": "order-receipt"
          }
        }
      },
      {
        "idempotencyKey": "order-1004-receipt",
        "message": {
          "to": {
            "externalId": "customer-0000"
          },
          "correlationId": "order-1004",
          "data": {
            "order_id": "1004",
            "total": "$7.25",
            "item_count": 1
          },
          "email": {
            "template": "order-receipt"
          }
        }
      }
    ]
  }'

const response = await fetch('https://api.kirora.io/v1/transactional/messages/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messages": [
      {
        "idempotencyKey": "order-1003-receipt",
        "message": {
          "to": {
            "externalId": "customer-4821"
          },
          "correlationId": "order-1003",
          "data": {
            "order_id": "1003",
            "total": "$24.00",
            "item_count": 2
          },
          "email": {
            "template": "order-receipt"
          }
        }
      },
      {
        "idempotencyKey": "order-1004-receipt",
        "message": {
          "to": {
            "externalId": "customer-0000"
          },
          "correlationId": "order-1004",
          "data": {
            "order_id": "1004",
            "total": "$7.25",
            "item_count": 1
          },
          "email": {
            "template": "order-receipt"
          }
        }
      }
    ]
  }),
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/transactional/messages/batch",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "messages": [
            {
                "idempotencyKey": "order-1003-receipt",
                "message": {
                    "to": {
                        "externalId": "customer-4821",
                    },
                    "correlationId": "order-1003",
                    "data": {
                        "order_id": "1003",
                        "total": "$24.00",
                        "item_count": 2,
                    },
                    "email": {
                        "template": "order-receipt",
                    },
                },
            },
            {
                "idempotencyKey": "order-1004-receipt",
                "message": {
                    "to": {
                        "externalId": "customer-0000",
                    },
                    "correlationId": "order-1004",
                    "data": {
                        "order_id": "1004",
                        "total": "$7.25",
                        "item_count": 1,
                    },
                    "email": {
                        "template": "order-receipt",
                    },
                },
            },
        ],
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "messages": [
	    {
	      "idempotencyKey": "order-1003-receipt",
	      "message": {
	        "to": {
	          "externalId": "customer-4821"
	        },
	        "correlationId": "order-1003",
	        "data": {
	          "order_id": "1003",
	          "total": "$24.00",
	          "item_count": 2
	        },
	        "email": {
	          "template": "order-receipt"
	        }
	      }
	    },
	    {
	      "idempotencyKey": "order-1004-receipt",
	      "message": {
	        "to": {
	          "externalId": "customer-0000"
	        },
	        "correlationId": "order-1004",
	        "data": {
	          "order_id": "1004",
	          "total": "$7.25",
	          "item_count": 1
	        },
	        "email": {
	          "template": "order-receipt"
	        }
	      }
	    }
	  ]
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/transactional/messages/batch", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.kirora.io/v1/transactional/messages/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));
request.Content = new StringContent(
    """
    {
      "messages": [
        {
          "idempotencyKey": "order-1003-receipt",
          "message": {
            "to": {
              "externalId": "customer-4821"
            },
            "correlationId": "order-1003",
            "data": {
              "order_id": "1003",
              "total": "$24.00",
              "item_count": 2
            },
            "email": {
              "template": "order-receipt"
            }
          }
        },
        {
          "idempotencyKey": "order-1004-receipt",
          "message": {
            "to": {
              "externalId": "customer-0000"
            },
            "correlationId": "order-1004",
            "data": {
              "order_id": "1004",
              "total": "$7.25",
              "item_count": 1
            },
            "email": {
              "template": "order-receipt"
            }
          }
        }
      ]
    }
    """,
    Encoding.UTF8,
    "application/json");

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 202

{
  "data": {
    "results": [
      {
        "idempotencyKey": "order-1003-receipt",
        "replayed": false,
        "messages": [
          {
            "id": "0192f3b0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
            "channel": "email",
            "status": "queued",
            "correlationId": "order-1003",
            "createdAt": "2026-11-17T08:30:00.000Z",
            "sendAt": null,
            "fallbackFor": null,
            "copy": null
          }
        ],
        "skippedChannels": [],
        "skippedCopies": []
      },
      {
        "idempotencyKey": "order-1004-receipt",
        "error": {
          "code": "NOT_FOUND",
          "message": "No contact matches `to`",
          "details": {
            "field": "to"
          }
        }
      }
    ]
  }
}