Transactional

Send up to 100 transactional messages

POST/v1/transactional/messages/batch

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

Each entry takes its own idempotencyKey, so retrying the whole batch never acts twice on an entry that already went through. About idempotency

Each entry is a single send (see POST /v1/transactional/messages) with its own idempotencyKey, answered on its own: results keeps the order of sends, each with its messages 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.

Request body

sendsobject[]required

at least 1 item · at most 100 items

2 child attributes

idempotencyKeystringrequired

As the Idempotency-Key header of a single send: one per message you mean.

8–255 characters

sendSendTransactionalInputrequired

11 child attributes

toobjectrequired

Who receives it.

One of 3 shapes

By contact id

1 child attribute

contactIdstringrequired

An existing contact.

uuid

By external id

5 child attributes

externalIdstringrequired

Your own id for the contact. Alone it must match an existing contact; with email or profile fields the contact is created or updated, as identify does.

1–255 characters

emailstringoptional

Sets or updates the contact email.

email · up to 320 characters

firstNamestring | nulloptional

1–100 characters

lastNamestring | nulloptional

1–100 characters

attributesobjectoptional

Custom attributes, merged key by key; null removes one. At most 50 keys and 16 KB.

By email

4 child attributes

emailstringrequired

The recipient's address. With profile fields the contact is created or updated, as identify does; alone, an email send creates a transactional-only contact when none has it, and a push-only send needs an existing contact.

email · up to 320 characters

firstNamestring | nulloptional

1–100 characters

lastNamestring | nulloptional

1–100 characters

attributesobjectoptional

Custom attributes, merged key by key; null removes one. At most 50 keys and 16 KB.

sensitivebooleanoptional

Set when the message carries a secret (a reset link, a one-time code): its content is never kept, whatever retainContent and the workspace's retention say.

correlationIdstringoptional

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

1–255 characters

retainContentbooleanoptional

false discards what was sent as soon as it is sent.

emailobjectoptional

Inline content (subject, from, html), or a stored templateId.

One of 2 shapes

Stored template

6 child attributes

templateIdstringrequired

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

dataobjectoptional

Values for the template's {{ data.* }} merge tags.

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.

Inline content

6 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–512000 characters

textstringoptional

The plain-text alternative.

1–512000 characters

fromstringrequired

The sender address, on a verified sending domain.

1–320 characters

replyTostringoptional

Where replies go.

pushobjectoptional

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

2 child attributes

pushProjectIdstringrequired

Reaches the contact's devices on every app of the project.

uuid

contentobjectrequired

13 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 2048 characters

imageUrlstringoptional

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

uri · up to 2048 characters

iconUrlstringoptional

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

uri · up to 2048 characters

dataobjectoptional

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

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

collapseKeystringoptional

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

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

ttlSecondsintegeroptional

Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).

min 0 · max 2419200

urgencystringoptional

high wakes the device now; normal lets it wait for a good moment to save battery. 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.

attachmentsEmailAttachmentInput[]optional

Files the email carries (not push): up to 10, 10 MB in all.

at least 1 item · at most 10 items

3 child attributes

filenamestringrequired

Its extension sets the type it is sent as.

1–255 characters

contentstringrequired

The file, base64-encoded.

base64

contentIdstringoptional

Shows an image inside the body instead of attaching it: the HTML refers to it as <img src="cid:<contentId>">.

threadingEmailThreadingInputoptional

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

2 child attributes

inReplyTostringrequired

The Message-ID of the email being replied to, angle brackets included.

referencesstring[]optional

The Message-IDs earlier in the conversation, oldest first (up to 20).

at least 1 item · at most 20 items

trackingTransactionalEmailTrackingInputoptional

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

2 child attributes

opensbooleanoptional

Track opens with a pixel.

default false

clicksbooleanoptional

Rewrite links to track clicks.

default false

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; deliver: first picks its channel when accepted.

date-time

deliverstringoptional

With both push and email: all sends each the contact can receive; first sends push when the contact has a reachable device, else email.

one of all, first · default "all"

Returns

Returns 202 Accepted with a TransactionalBatchResult in data. Otherwise returns an error; Errors lists every code and which to retry.

resultsobject[]required

One of 2 shapes

Accepted

3 child attributes

idempotencyKeystringrequired

replayedbooleanrequired

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

messagesTransactionalMessage[]required

6 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 email goes out; null when it went at once.

date-time

Rejected

2 child attributes

idempotencyKeystringrequired

errorobjectrequired

4 child attributes

codestringrequired: one of BAD_REQUEST, ALREADY_EXISTS, CONFLICT, IN_USE, FORBIDDEN, INTERNAL_ERROR, NOT_FOUND, RATE_LIMITED, REVISION_CONFLICT, SERVICE_UNAVAILABLE, UNAUTHORIZED, VALIDATION_ERROR, API_KEY_IP_NOT_ALLOWED, AGENT_CONFIRMATION_REQUIRED, 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, PLAN_FEATURE_UNAVAILABLE, CAMPAIGN_AUDIENCE_CONFLICT, EMPTY_AUDIENCE, INVALID_CAMPAIGN_CONTENT, DRAFT_INCOMPLETE, INVALID_SCHEDULE, UNSUPPORTED_CHANNEL, POSTAL_ADDRESS_MISSING, CONSENT_MISSING, SUPPRESSED, SIGNUP_BLOCKED, INVALID_SENDER_ADDRESS, SENDING_DOMAIN_DMARC_MISSING, SENDING_DOMAIN_IDENTITY_CONFLICT, SENDING_DOMAIN_UNVERIFIED, IDEMPOTENCY_KEY_REUSED, CONTENT_NOT_RETAINED, RECIPIENT_EMAIL_MISSING, TEMPLATE_NOT_PUBLISHED, TEMPLATE_ENVELOPE_INCOMPLETE, PUSH_APP_NOT_READY, PUSH_DESTINATION_MISSING
messagestringrequired
detailsobjectoptional
requestIdstringoptional

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

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({
    "sends": [
      {
        "idempotencyKey": "order-1001-receipt",
        "send": {
          "to": {
            "externalId": "customer-4821"
          },
          "correlationId": "order-1001",
          "email": {
            "templateId": "order-receipt",
            "data": {
              "orderNumber": "1001",
              "total": "$45.00",
              "items": 3
            }
          }
        }
      },
      {
        "idempotencyKey": "order-1002-receipt",
        "send": {
          "to": {
            "externalId": "customer-5307"
          },
          "correlationId": "order-1002",
          "email": {
            "templateId": "order-receipt",
            "data": {
              "orderNumber": "1002",
              "total": "$18.50",
              "items": 1
            }
          }
        }
      }
    ]
  }),
});
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={
        "sends": [
            {
                "idempotencyKey": "order-1001-receipt",
                "send": {
                    "to": {
                        "externalId": "customer-4821",
                    },
                    "correlationId": "order-1001",
                    "email": {
                        "templateId": "order-receipt",
                        "data": {
                            "orderNumber": "1001",
                            "total": "$45.00",
                            "items": 3,
                        },
                    },
                },
            },
            {
                "idempotencyKey": "order-1002-receipt",
                "send": {
                    "to": {
                        "externalId": "customer-5307",
                    },
                    "correlationId": "order-1002",
                    "email": {
                        "templateId": "order-receipt",
                        "data": {
                            "orderNumber": "1002",
                            "total": "$18.50",
                            "items": 1,
                        },
                    },
                },
            },
        ],
    },
)
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "sends": [
	    {
	      "idempotencyKey": "order-1001-receipt",
	      "send": {
	        "to": {
	          "externalId": "customer-4821"
	        },
	        "correlationId": "order-1001",
	        "email": {
	          "templateId": "order-receipt",
	          "data": {
	            "orderNumber": "1001",
	            "total": "$45.00",
	            "items": 3
	          }
	        }
	      }
	    },
	    {
	      "idempotencyKey": "order-1002-receipt",
	      "send": {
	        "to": {
	          "externalId": "customer-5307"
	        },
	        "correlationId": "order-1002",
	        "email": {
	          "templateId": "order-receipt",
	          "data": {
	            "orderNumber": "1002",
	            "total": "$18.50",
	            "items": 1
	          }
	        }
	      }
	    }
	  ]
	}`)
	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()

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

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": "2030-03-14T09:30:00.000Z",
            "sendAt": null
          }
        ]
      },
      {
        "idempotencyKey": "order-1002-receipt",
        "replayed": false,
        "messages": [
          {
            "id": "0192f3b0-3c4d-7e5f-8a61-7c8d9e0f1a2b",
            "channel": "email",
            "status": "queued",
            "correlationId": "order-1002",
            "createdAt": "2030-03-14T09:30:00.000Z",
            "sendAt": null
          }
        ]
      }
    ]
  }
}

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

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({
    "sends": [
      {
        "idempotencyKey": "order-1003-receipt",
        "send": {
          "to": {
            "externalId": "customer-4821"
          },
          "correlationId": "order-1003",
          "email": {
            "templateId": "order-receipt",
            "data": {
              "orderNumber": "1003",
              "total": "$24.00",
              "items": 2
            }
          }
        }
      },
      {
        "idempotencyKey": "order-1004-receipt",
        "send": {
          "to": {
            "externalId": "customer-0000"
          },
          "correlationId": "order-1004",
          "email": {
            "templateId": "order-receipt",
            "data": {
              "orderNumber": "1004",
              "total": "$7.25",
              "items": 1
            }
          }
        }
      }
    ]
  }),
});
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={
        "sends": [
            {
                "idempotencyKey": "order-1003-receipt",
                "send": {
                    "to": {
                        "externalId": "customer-4821",
                    },
                    "correlationId": "order-1003",
                    "email": {
                        "templateId": "order-receipt",
                        "data": {
                            "orderNumber": "1003",
                            "total": "$24.00",
                            "items": 2,
                        },
                    },
                },
            },
            {
                "idempotencyKey": "order-1004-receipt",
                "send": {
                    "to": {
                        "externalId": "customer-0000",
                    },
                    "correlationId": "order-1004",
                    "email": {
                        "templateId": "order-receipt",
                        "data": {
                            "orderNumber": "1004",
                            "total": "$7.25",
                            "items": 1,
                        },
                    },
                },
            },
        ],
    },
)
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "sends": [
	    {
	      "idempotencyKey": "order-1003-receipt",
	      "send": {
	        "to": {
	          "externalId": "customer-4821"
	        },
	        "correlationId": "order-1003",
	        "email": {
	          "templateId": "order-receipt",
	          "data": {
	            "orderNumber": "1003",
	            "total": "$24.00",
	            "items": 2
	          }
	        }
	      }
	    },
	    {
	      "idempotencyKey": "order-1004-receipt",
	      "send": {
	        "to": {
	          "externalId": "customer-0000"
	        },
	        "correlationId": "order-1004",
	        "email": {
	          "templateId": "order-receipt",
	          "data": {
	            "orderNumber": "1004",
	            "total": "$7.25",
	            "items": 1
	          }
	        }
	      }
	    }
	  ]
	}`)
	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()

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

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": "2030-03-14T09:30:00.000Z",
            "sendAt": null
          }
        ]
      },
      {
        "idempotencyKey": "order-1004-receipt",
        "error": {
          "code": "NOT_FOUND",
          "message": "No contact matches `to`",
          "details": {
            "field": "to"
          }
        }
      }
    ]
  }
}