Tenant
SDK reference for managing tenant settings and the sandbox whitelist in Kraiter.
The kraiter.tenant namespace provides methods for retrieving tenant details and managing the sandbox whitelist. While your tenant is in sandbox mode, emails can only be sent to whitelisted recipient addresses.
get
Retrieves the current tenant's details, including plan, sending status, and sandbox whitelist.
const tenant = await kraiter.tenant.get();
console.log(tenant.sendingStatus); // "sandbox" | "enabled" | "paused"
console.log(tenant.sandboxWhitelist); // ["test@example.com"]Returns
Promise<TenantInfo | null> — the tenant object, or null if not provisioned.
TenantInfo object
| Field | Type | Description |
|---|---|---|
tenantId | string | Unique tenant ID. |
name | string | Organisation name. |
plan | string | Current plan: "free", "starter", or "pro". |
sendingStatus | string | Sending status: "enabled", "paused", or "sandbox". |
sandboxWhitelist | string[] | Email addresses whitelisted for sandbox sending. |
createdAt | string | ISO 8601 timestamp. |
updatedAt | string | ISO 8601 timestamp. |
The full object also includes billing and usage fields such as defaultFromAddress, preferredRegion, contactCount, monthlySendCount, billingStatus, stripeCustomerId, and stripeSubscriptionId.
update
Updates the current tenant's settings. Only the fields you include are changed.
const tenant = await kraiter.tenant.update({
name: 'Acme Inc.',
defaultFromAddress: 'hello@acme.com',
sendingStatus: 'enabled',
});Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | No | Organisation name. |
defaultFromAddress | string | null | No | Default from address for sends. Pass null to clear it. |
sendingStatus | "enabled" | "paused" | "sandbox" | No | The tenant's sending mode. |
preferredRegion | string | null | No | Preferred AWS region for sending. Pass null to clear it. |
Returns
Promise<TenantInfo> — the updated tenant object.
listSandboxWhitelist
Returns the list of email addresses whitelisted for sandbox sending.
const { emails } = await kraiter.tenant.listSandboxWhitelist();
for (const email of emails) {
console.log(email);
}Returns
Promise<SandboxWhitelistResponse> — { emails: string[] }.
addToSandboxWhitelist
Adds an email address to the sandbox whitelist. While in sandbox mode, only whitelisted addresses can receive emails. Maximum 50 emails.
const { emails } = await kraiter.tenant.addToSandboxWhitelist("test@example.com");
console.log(emails); // ["test@example.com"]Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | The email address to whitelist. |
Returns
Promise<SandboxWhitelistResponse> — the updated whitelist.
Errors
| Code | When |
|---|---|
VALIDATION_ERROR | The email address is invalid or the whitelist has reached the 50-email limit. |
removeFromSandboxWhitelist
Removes an email address from the sandbox whitelist. Emails to this address will be blocked until re-added.
const { emails } = await kraiter.tenant.removeFromSandboxWhitelist("test@example.com");
console.log(emails); // []Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | The email address to remove. |
Returns
Promise<SandboxWhitelistResponse> — the updated whitelist.
getSesAccountStatus
Returns the SES account status for the current tenant, including sandbox state and sending quotas.
const status = await kraiter.tenant.getSesAccountStatus();
if (status.connected) {
console.log(status.region, status.sandbox);
console.log(status.quotas.max24HourSend);
} else {
console.log('Not connected:', status.message);
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
region | string | No | AWS region to check, passed as { region }. Defaults to the tenant's configured region. |
Returns
Promise<SESAccountStatus> — a discriminated union on connected. When connected is true, the object includes region, sandbox, sendingEnabled, quotas, and binding; when false, it includes optional status, message, error, and details fields.