Kereru API (4.0.0)

Download OpenAPI specification:

Kereru message sending and management API. Provides endpoints for querying and managing email and SMS message queues.

Process Lambda (Firecrest-Kereru-Process)

A scheduled Lambda invoked hourly via EventBridge (UTC) that sends queued messages.

Behaviour:

Queries EmailQueue and SMSQueue for packets with Status = NotSent (0) or Attempted (1)
Operates across all tenancies (filtered to those with eligible packets)
Loads the tenancy profile for each tenancy to check service enablement (EmailServiceEnabled, SMSServiceEnabled)
Sends packets ordered by Priority DESC, CreatedOn ASC
Skips packets older than 24 hours (configurable) or with more than 5 attempts (configurable)

EventBridge event properties (all optional, with defaults):

Property	Type	Default	Description
Cutoff	DateTime?	null	Explicit cutoff date. Takes precedence over MaxAgeMinutes.
MaxAgeMinutes	int	1440	Fallback age limit in minutes when Cutoff is not set.
Tenancy	string?	null	Restrict processing to a single tenancy.
IncludeEmail	bool	true	Whether to process queued emails.
IncludeSMS	bool	true	Whether to process queued SMS messages.
MaxAttempts	int	5	Maximum prior attempts for a packet to still be eligible.
MinPriority	int	0	Minimum priority (Low=0, Medium=1, High=2).

Email

Endpoints for email queue management.

Resend Email

Resends an existing email packet to SendGrid.

The packet is fetched from the queue by its ID and tenancy, then sent again via SendGrid directly. On success, the packet's queue status is set to ResentDirect (21), its delivery status is reset to Unknown (0), SentOn is updated, and the attempt counter is incremented.

Required Grants:

kereru:email:resend

path Parameters

packet

required

string <uuid>

The GUID of the email packet to resend.

Responses

Send Email

Sends one or more email packets immediately via SendGrid and records them in the email queue. Accepts a single object or an array of objects.

FromEmail falls back to the tenancy profile's FromEmail, then to the service default. If EmailServiceEnabled or AllowDirectSendEmail is false on the profile, packets are queued instead of sent.

Response is a single EmailPacket if one was provided, or an array of EmailPackets if multiple.

Required Grants:

kereru:email:send

Request Body schema:
application/json - single
required

tenancy	string
id	string <uuid>
code	string Default: ""
	object (Email Address)
	Array of objects (Email Address)
	Array of objects (Email Address)
	Array of objects (Email Address)
subject	string
inReplyTo	string or null
htmlMessage	string
plainTextMessage	string
priority	integer Enum: 0 1 2 Priority levels: Low (0), Medium (1), High (2)
status	integer Enum: 0 1 10 11 20 21 30 31 Queue statuses: NotSent (0), Attempted (1), Sent (10), SentDirect (11), Resent (20), ResentDirect (21), Error (30), ErrorNoEmailCode (31)
deliveryStatus	integer Enum: 0 1 10 11 20 Delivery statuses: Unknown (0), Delivered (1), Bounced (10), Rejected (11), Opened (20). Updated via SendGrid webhook callbacks.
attempts	integer
errorMessage	string
batchID	string or null <uuid>
originID	string or null <uuid>
createdOn	string <date-time>
sentOn	string or null <date-time>
updatedOn	string <date-time> Last updated timestamp. Updated when delivery status changes.

Responses

Request samples

Payload

Content type

application/json - single

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"subject": "Welcome to Acme",
"inReplyTo": "string",
"htmlMessage": "string",
"plainTextMessage": "string",
"priority": 0,
"status": 0,
"deliveryStatus": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}

Response samples

200

Content type

application/json - single

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"subject": "Welcome to Acme",
"inReplyTo": "string",
"htmlMessage": "string",
"plainTextMessage": "string",
"priority": 0,
"status": 0,
"deliveryStatus": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}

Queue Email

Queues one or more email packets for later sending and records them in the email queue. Accepts a single object or an array of objects.

FromEmail falls back to the tenancy profile's FromEmail, then to the service default.

Response is a single EmailPacket if one was provided, or an array of EmailPackets if multiple.

Required Grants:

kereru:email:queue

Request Body schema:
application/json - single
required

tenancy	string
id	string <uuid>
code	string Default: ""
	object (Email Address)
	Array of objects (Email Address)
	Array of objects (Email Address)
	Array of objects (Email Address)
subject	string
inReplyTo	string or null
htmlMessage	string
plainTextMessage	string
priority	integer Enum: 0 1 2 Priority levels: Low (0), Medium (1), High (2)
status	integer Enum: 0 1 10 11 20 21 30 31 Queue statuses: NotSent (0), Attempted (1), Sent (10), SentDirect (11), Resent (20), ResentDirect (21), Error (30), ErrorNoEmailCode (31)
deliveryStatus	integer Enum: 0 1 10 11 20 Delivery statuses: Unknown (0), Delivered (1), Bounced (10), Rejected (11), Opened (20). Updated via SendGrid webhook callbacks.
attempts	integer
errorMessage	string
batchID	string or null <uuid>
originID	string or null <uuid>
createdOn	string <date-time>
sentOn	string or null <date-time>
updatedOn	string <date-time> Last updated timestamp. Updated when delivery status changes.

Responses

Request samples

Payload

Content type

application/json - single

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"subject": "Welcome to Acme",
"inReplyTo": "string",
"htmlMessage": "string",
"plainTextMessage": "string",
"priority": 0,
"status": 0,
"deliveryStatus": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}

Response samples

200

Content type

application/json - single

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"subject": "Welcome to Acme",
"inReplyTo": "string",
"htmlMessage": "string",
"plainTextMessage": "string",
"priority": 0,
"status": 0,
"deliveryStatus": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}

Query Emails

Queries the email queue with filtering, pagination, and ordering.

Tenancy is derived from request headers (PrimaryDomain + Application path parameter) and cannot be overridden in the request body.

All filter properties are optional. Send {} for defaults (page 0, 20 items, ordered by CreatedOn DESC, ID ASC).

Text filters (Subject, ErrorMessage, HtmlMessage, PlainTextMessage) use SQL LIKE — caller provides wildcards (e.g. %invoice% for contains). Address filters (FromEmail, ToEmail, CCEmail, BCCEmail, AnyEmail) also use LIKE via EXISTS subqueries. InReplyTo uses exact match.

Multiple address filters use AND semantics — all specified filters must independently match.

Required Grants:

kereru:email:get
kereru:email:list

Request Body schema: application/json
optional

page	integer Default: 0 Zero-indexed page number.
pageSize	integer Default: 20
orderBy	string or null Comma-separated column/direction pairs. Default: UpdatedOn DESC, ID ASC.
id	string or null <uuid>
subject	string or null LIKE filter. Caller provides wildcards.
inReplyTo	string or null Exact match on message ID reference.
status	integer or null
statusIn	Array of integers or null
priority	integer or null
priorityIn	Array of integers or null
attempts	integer or null
attemptsMin	integer or null
attemptsMax	integer or null
errorMessage	string or null LIKE filter.
htmlMessage	string or null LIKE filter.
plainTextMessage	string or null LIKE filter.
createdOnFrom	string or null <date-time>
createdOnTo	string or null <date-time>
sentOnFrom	string or null <date-time>
sentOnTo	string or null <date-time>
originID	string or null <uuid>
batchID	string or null <uuid>
deliveryStatus	integer or null Exact match. Delivery statuses: Unknown (0), Delivered (1), Bounced (10), Rejected (11), Opened (20).
deliveryStatusIn	Array of integers or null IN filter for delivery status values.
updatedOnFrom	string or null <date-time>
updatedOnTo	string or null <date-time>
fromEmail	string or null LIKE filter on From address.
toEmail	string or null LIKE filter on To addresses.
ccEmail	string or null LIKE filter on CC addresses.
bccEmail	string or null LIKE filter on BCC addresses.
anyEmail	string or null LIKE filter across all address types.

Responses

Request samples

Payload

Content type

application/json

{"page": 0,
"pageSize": 20,
"orderBy": "UpdatedOn DESC, ID ASC",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"subject": "string",
"inReplyTo": "string",
"status": 0,
"statusIn": [0
],
"priority": 0,
"priorityIn": [0
],
"attempts": 0,
"attemptsMin": 0,
"attemptsMax": 0,
"errorMessage": "string",
"htmlMessage": "string",
"plainTextMessage": "string",
"createdOnFrom": "2019-08-24T14:15:22Z",
"createdOnTo": "2019-08-24T14:15:22Z",
"sentOnFrom": "2019-08-24T14:15:22Z",
"sentOnTo": "2019-08-24T14:15:22Z",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"deliveryStatus": 0,
"deliveryStatusIn": [0
],
"updatedOnFrom": "2019-08-24T14:15:22Z",
"updatedOnTo": "2019-08-24T14:15:22Z",
"fromEmail": "string",
"toEmail": "string",
"ccEmail": "string",
"bccEmail": "string",
"anyEmail": "string"
}

Response samples

200

Content type

application/json

{"items": [{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"subject": "Welcome to Acme",
"inReplyTo": "string",
"htmlMessage": "string",
"plainTextMessage": "string",
"priority": 0,
"status": 0,
"deliveryStatus": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}
],
"maxAvailableItems": 0
}

Email Template

Endpoints for email template CRUD and template-based sending.

List Templates

Lists all email templates for the tenancy, ordered by Name ascending.

Required Grants:

kereru:template:list

Responses

Response samples

200

Content type

application/json

[{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "welcome-email",
"name": "Welcome Email",
"subject": "Welcome @@FirstName@@!",
"plainTextMessage": "string",
"htmlMessage": "string",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"createdOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}
]

Create Template

Creates a new email template.

Tenancy is set automatically from request headers. Code must be unique within the tenancy. Template messages support @@variable@@ tokens for variable replacement when sending.

Required Grants:

kereru:template:create

Request Body schema: application/json
required

tenancy	string
id	string <uuid>
code	string Unique template code within the tenancy.
name	string
subject	string Supports @@variable@@ token replacement.
plainTextMessage	string Supports @@variable@@ token replacement.
htmlMessage	string Supports @@variable@@ token replacement.
originID	string or null <uuid>
batchID	string or null <uuid>
	object (Email Address)
	Array of objects (Email Address)
	Array of objects (Email Address)
	Array of objects (Email Address)
createdOn	string <date-time>
updatedOn	string <date-time>

Responses

Request samples

Payload

Content type

application/json

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "welcome-email",
"name": "Welcome Email",
"subject": "Welcome @@FirstName@@!",
"plainTextMessage": "string",
"htmlMessage": "string",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"createdOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}

Response samples

200

Content type

application/json

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "welcome-email",
"name": "Welcome Email",
"subject": "Welcome @@FirstName@@!",
"plainTextMessage": "string",
"htmlMessage": "string",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"createdOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}

Get Template

Gets an email template by its code or ID.

Required Grants:

kereru:template:get

path Parameters

code

required

string

The template code (string) or ID (GUID).

Responses

Response samples

200

Content type

application/json

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "welcome-email",
"name": "Welcome Email",
"subject": "Welcome @@FirstName@@!",
"plainTextMessage": "string",
"htmlMessage": "string",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"createdOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}

Update Template

Updates an existing email template by code or ID.

The template ID is preserved from the existing record.

Required Grants:

kereru:template:update

path Parameters

code

required

string

The template code (string) or ID (GUID).

Request Body schema: application/json
required

tenancy	string
id	string <uuid>
code	string Unique template code within the tenancy.
name	string
subject	string Supports @@variable@@ token replacement.
plainTextMessage	string Supports @@variable@@ token replacement.
htmlMessage	string Supports @@variable@@ token replacement.
originID	string or null <uuid>
batchID	string or null <uuid>
	object (Email Address)
	Array of objects (Email Address)
	Array of objects (Email Address)
	Array of objects (Email Address)
createdOn	string <date-time>
updatedOn	string <date-time>

Responses

Request samples

Payload

Content type

application/json

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "welcome-email",
"name": "Welcome Email",
"subject": "Welcome @@FirstName@@!",
"plainTextMessage": "string",
"htmlMessage": "string",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"createdOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}

Response samples

200

Content type

application/json

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "welcome-email",
"name": "Welcome Email",
"subject": "Welcome @@FirstName@@!",
"plainTextMessage": "string",
"htmlMessage": "string",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"createdOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}

Delete Template

Deletes an email template by code or ID.

Required Grants:

kereru:template:delete

path Parameters

code

required

string

The template code (string) or ID (GUID).

Responses

Send With Template

Resolves a template, applies @@variable@@ replacement using the provided Variables dictionary, applies any override fields, sends the email immediately via SendGrid, and records the packet in the email queue.

The Subject override (if provided) also has variable replacement applied.

Response is the constructed EmailPacket after sending and recording.

Required Grants:

kereru:template:get
kereru:email:send

path Parameters

code

required

string

The template code (string) or ID (GUID).

Request Body schema: application/json
required

code required	string The code of the template to use.
	object Variables for @@Key@@ token replacement in template fields.
	object (Email Address) Overrides the template FromEmail when specified.
	Array of objects or null (Email Address) Overrides the template ToEmail when specified.
	Array of objects or null (Email Address) Overrides the template CCEmail when specified.
	Array of objects or null (Email Address) Overrides the template BCCEmail when specified.
subject	string or null Overrides the template Subject when specified. Also has variable replacement applied.
inReplyTo	string or null Overrides the packet InReplyTo when specified.
priority	integer or null Overrides the packet Priority when specified.
originID	string or null <uuid> Overrides the template OriginID when specified.
batchID	string or null <uuid> Overrides the template BatchID when specified.

Responses

Request samples

Payload

Content type

application/json

{"code": "welcome-email",
"variables": {"FirstName": "John",
"CompanyName": "Acme Corp"
},
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"subject": "string",
"inReplyTo": "string",
"priority": 0,
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42"
}

Response samples

200

Content type

application/json

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"subject": "Welcome to Acme",
"inReplyTo": "string",
"htmlMessage": "string",
"plainTextMessage": "string",
"priority": 0,
"status": 0,
"deliveryStatus": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}

Queue With Template

Resolves a template, applies @@variable@@ replacement using the provided Variables dictionary, applies any override fields, queues the email for later sending, and records the packet in the email queue.

The Subject override (if provided) also has variable replacement applied.

Response is the constructed EmailPacket after queuing and recording.

Required Grants:

kereru:template:get
kereru:email:queue

path Parameters

code

required

string

The template code (string) or ID (GUID).

Request Body schema: application/json
required

code required	string The code of the template to use.
	object Variables for @@Key@@ token replacement in template fields.
	object (Email Address) Overrides the template FromEmail when specified.
	Array of objects or null (Email Address) Overrides the template ToEmail when specified.
	Array of objects or null (Email Address) Overrides the template CCEmail when specified.
	Array of objects or null (Email Address) Overrides the template BCCEmail when specified.
subject	string or null Overrides the template Subject when specified. Also has variable replacement applied.
inReplyTo	string or null Overrides the packet InReplyTo when specified.
priority	integer or null Overrides the packet Priority when specified.
originID	string or null <uuid> Overrides the template OriginID when specified.
batchID	string or null <uuid> Overrides the template BatchID when specified.

Responses

Request samples

Payload

Content type

application/json

{"code": "welcome-email",
"variables": {"FirstName": "John",
"CompanyName": "Acme Corp"
},
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"subject": "string",
"inReplyTo": "string",
"priority": 0,
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42"
}

Response samples

200

Content type

application/json

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "",
"fromEmail": {"email": "user@example.com",
"name": "John Smith"
},
"toEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"ccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"bccEmail": [{"email": "user@example.com",
"name": "John Smith"
}
],
"subject": "Welcome to Acme",
"inReplyTo": "string",
"htmlMessage": "string",
"plainTextMessage": "string",
"priority": 0,
"status": 0,
"deliveryStatus": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z"
}

SMS

Endpoints for SMS queue management.

Query SMS

Queries the SMS queue with filtering, pagination, and ordering.

Tenancy is derived from request headers (PrimaryDomain + Application path parameter) and cannot be overridden in the request body.

All filter properties are optional. Send {} for defaults (page 0, 20 items, ordered by CreatedOn DESC, ID ASC).

Text filters (Reference, Message, ErrorMessage) use SQL LIKE — caller provides wildcards (e.g. %keyword% for contains). RecipientNumber filter uses LIKE via an EXISTS subquery.

Required Grants:

kereru:sms:get
kereru:sms:list

Request Body schema: application/json
optional

page	integer Default: 0 Zero-indexed page number.
pageSize	integer Default: 20
orderBy	string or null Comma-separated column/direction pairs. Default: CreatedOn DESC, ID ASC.
id	string or null <uuid>
reference	string or null LIKE filter. Caller provides wildcards.
message	string or null LIKE filter. Caller provides wildcards.
status	integer or null
statusIn	Array of integers or null
priority	integer or null
priorityIn	Array of integers or null
attempts	integer or null
attemptsMin	integer or null
attemptsMax	integer or null
errorMessage	string or null LIKE filter.
createdOnFrom	string or null <date-time>
createdOnTo	string or null <date-time>
sentOnFrom	string or null <date-time>
sentOnTo	string or null <date-time>
originID	string or null <uuid>
batchID	string or null <uuid>
recipientNumber	string or null LIKE filter on recipient numbers.

Responses

Request samples

Payload

Content type

application/json

{"page": 0,
"pageSize": 20,
"orderBy": "CreatedOn DESC, ID ASC",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"reference": "string",
"message": "string",
"status": 0,
"statusIn": [0
],
"priority": 0,
"priorityIn": [0
],
"attempts": 0,
"attemptsMin": 0,
"attemptsMax": 0,
"errorMessage": "string",
"createdOnFrom": "2019-08-24T14:15:22Z",
"createdOnTo": "2019-08-24T14:15:22Z",
"sentOnFrom": "2019-08-24T14:15:22Z",
"sentOnTo": "2019-08-24T14:15:22Z",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"recipientNumber": "string"
}

Response samples

200

Content type

application/json

{"items": [{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"reference": "string",
"toSMS": ["+6421000000"
],
"message": "string",
"priority": 0,
"status": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z"
}
],
"maxAvailableItems": 0
}

Send SMS

Sends one or more SMS packets immediately via TNZ and records them in the SMS queue. Accepts a single object or an array of objects.

If SMSServiceEnabled or AllowDirectSendSMS is false on the profile, packets are queued instead of sent.

Response is a single SMSPacket if one was provided, or an array of SMSPackets if multiple.

Required Grants:

kereru:sms:send

Request Body schema:
application/json - single
required

tenancy	string
id	string <uuid>
reference	string or null
toSMS	Array of strings
message	string
priority	integer Enum: 0 1 2 Priority levels: Low (0), Medium (1), High (2)
status	integer Enum: 0 1 10 11 20 21 30 31 Queue statuses: NotSent (0), Attempted (1), Sent (10), SentDirect (11), Resent (20), ResentDirect (21), Error (30), ErrorNoEmailCode (31)
attempts	integer
errorMessage	string
batchID	string or null <uuid>
originID	string or null <uuid>
createdOn	string <date-time>
sentOn	string or null <date-time>

Responses

Request samples

Payload

Content type

application/json - single

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"reference": "string",
"toSMS": ["+6421000000"
],
"message": "string",
"priority": 0,
"status": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z"
}

Response samples

200

Content type

application/json - single

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"reference": "string",
"toSMS": ["+6421000000"
],
"message": "string",
"priority": 0,
"status": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z"
}

Queue SMS

Queues one or more SMS packets for later sending and records them in the SMS queue. Accepts a single object or an array of objects.

Response is a single SMSPacket if one was provided, or an array of SMSPackets if multiple.

Required Grants:

kereru:sms:queue

Request Body schema:
application/json - single
required

tenancy	string
id	string <uuid>
reference	string or null
toSMS	Array of strings
message	string
priority	integer Enum: 0 1 2 Priority levels: Low (0), Medium (1), High (2)
status	integer Enum: 0 1 10 11 20 21 30 31 Queue statuses: NotSent (0), Attempted (1), Sent (10), SentDirect (11), Resent (20), ResentDirect (21), Error (30), ErrorNoEmailCode (31)
attempts	integer
errorMessage	string
batchID	string or null <uuid>
originID	string or null <uuid>
createdOn	string <date-time>
sentOn	string or null <date-time>

Responses

Request samples

Payload

Content type

application/json - single

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"reference": "string",
"toSMS": ["+6421000000"
],
"message": "string",
"priority": 0,
"status": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z"
}

Response samples

200

Content type

application/json - single

{"tenancy": "acme.org.nz.core",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"reference": "string",
"toSMS": ["+6421000000"
],
"message": "string",
"priority": 0,
"status": 0,
"attempts": 0,
"errorMessage": "string",
"batchID": "56707290-2f9b-4967-9c9d-1b759fac6d42",
"originID": "aad7996f-780d-4b0a-9fb2-c7b70efff27f",
"createdOn": "2019-08-24T14:15:22Z",
"sentOn": "2019-08-24T14:15:22Z"
}

Webhook URLs

Webhook callback endpoints for 3rd party services.

SendGrid Delivery Status Webhook

Receives delivery status updates from SendGrid's Event Webhook.

This endpoint is called by SendGrid, not by application clients. It does not require an API key but uses a dedicated callback authorizer.

The request body is a JSON array of SendGrid event objects. Each event is processed independently:

Events without a valid KereruID custom argument are skipped.
Events with unrecognised event types are skipped.
DeliveryStatus only advances forward (e.g. Delivered will not overwrite Opened).

SendGrid event type to DeliveryStatus mapping:

SendGrid Event	DeliveryStatus
delivered	Delivered (1)
bounce	Bounced (10)
blocked, dropped, spamreport	Rejected (11)
open, click	Opened (20)

Request Body schema: application/json
required

Array

event	string Enum: "delivered" "open" "click" "bounce" "blocked" "dropped" "spamreport" "deferred" "processed" SendGrid event type. Mapped to DeliveryStatus: delivered → Delivered (1), open/click → Opened (2), bounce → Bounced (10), blocked/dropped/spamreport → Rejected (11). Other event types are ignored.
KereruID	string <uuid> The Kereru email packet ID. Events without a valid KereruID are skipped.

Responses

Request samples

Payload

Content type

application/json

[{"event": "delivered",
"KereruID": "550e8400-e29b-41d4-a716-446655440000"
},
{"event": "open",
"KereruID": "550e8400-e29b-41d4-a716-446655440000"
}
]

Kereru API (4.0.0)

Process Lambda (Firecrest-Kereru-Process)

Email

Resend Email

path Parameters

Responses

Send Email

Request Body schema: application/json - singleapplication/json - multipleapplication/json - singlerequired

Responses

Request samples

Response samples

Queue Email

Request Body schema: application/json - singleapplication/json - multipleapplication/json - singlerequired

Responses

Request samples

Response samples

Query Emails

Request Body schema: application/jsonoptional

Responses

Request samples

Response samples

Email Template

List Templates

Responses

Response samples

Create Template

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get Template

path Parameters

Responses

Response samples

Update Template

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete Template

path Parameters

Responses

Send With Template

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Queue With Template

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

SMS

Query SMS

Request Body schema: application/jsonoptional

Responses

Request samples

Response samples

Send SMS

Request Body schema: application/json - singleapplication/json - multipleapplication/json - singlerequired

Responses

Request samples

Response samples

Queue SMS

Request Body schema: application/json - singleapplication/json - multipleapplication/json - singlerequired

Responses

Request samples

Response samples

Webhook URLs

SendGrid Delivery Status Webhook

Request Body schema: application/jsonrequired

Responses

Request samples

Request Body schema:
application/json - single
required

Request Body schema:
application/json - single
required

Request Body schema: application/json
optional

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
optional

Request Body schema:
application/json - single
required

Request Body schema:
application/json - single
required

Request Body schema: application/json
required