Email Templates

White-label organizations can rewrite the copy of the transactional email Blue sends on their behalf. An email template is an EmailTemplate object, keyed to one EmailTemplateType per organization. You override the pieces you care about — subject line, body, call-to-action, footer — and Blue renders them in place of its defaults.

Today there is exactly one template type: INVITATION, the email a new member receives when invited to a workspace. The customization surface is intentionally narrow — this is not a general transactional-email engine, just an override for the invitation copy.

Use createEmailTemplate and updateEmailTemplate to manage the copy, sendTestEmail to preview it against sample data, and emailTemplate / emailTemplates to read it back. Branding email this way requires the company-level white_label feature for every write; the two read queries only require organization membership.

Create a template

Use the createEmailTemplate mutation to define the override for a template type. It takes the target organization (companyId) and the type, plus any of the copy fields you want to set. Omitted copy fields fall back to Blue’s defaults at render time.

mutation CreateEmailTemplate {
  createEmailTemplate(
    input: {
      companyId: "company_123"
      type: INVITATION
      enabled: true
      subject: "You've been invited to {{company}}"
      body: "{{name}}, join your team on {{company}} to start collaborating."
      ctaText: "Accept invitation"
      footer: "Sent by {{company}} via Blue."
    }
  ) {
    id
    type
    enabled
    subject
  }
}

The companyId argument accepts an organization ID or slug.

CreateEmailTemplateInput

EmailTemplateType

Update a template

Use the updateEmailTemplate mutation to change the copy of an existing template. Identify it by id (the type is fixed at creation and cannot be changed here). Only the fields you pass are written.

mutation UpdateEmailTemplate {
  updateEmailTemplate(
    input: { id: "template_123", subject: "Your invitation to {{company}} is ready", enabled: true }
  ) {
    id
    subject
    enabled
    updatedAt
  }
}

UpdateEmailTemplateInput

Delete a template

Use the deleteEmailTemplate mutation to remove an override by id. Once deleted, the corresponding email reverts to Blue’s default copy. This mutation returns a bare Boolean (true on success), so it takes no sub-selection.

mutation DeleteEmailTemplate {
  deleteEmailTemplate(id: "template_123")
}

{ "data": { "deleteEmailTemplate": true } }

Send a test email

Use the sendTestEmail mutation to dispatch a one-off rendering of a template so you can preview your copy before it goes live. Blue renders the template with sample data — the recipient’s first name (falling back to "User"), their email, the organization’s name, and the name of the organization’s first workspace — then sends it as a real message to email. It returns Boolean (true once dispatched).

mutation SendTestEmail {
  sendTestEmail(input: { email: "[email protected]", emailTemplateId: "template_123" })
}

{ "data": { "sendTestEmail": true } }

SendTestEmailInput

Fetch a template by type

Use the emailTemplate query to read the single template configured for the context organization by type. The organization is taken from your X-Bloo-Company-ID header. Returns null if no override exists for that type. This query requires only organization membership — not the white_label feature.

query InvitationTemplate {
  emailTemplate(type: INVITATION) {
    id
    type
    enabled
    subject
    body
    ctaText
    ctaLink
    footer
  }
}

{
  "data": {
    "emailTemplate": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "type": "INVITATION",
      "enabled": true,
      "subject": "You've been invited to {{company}}",
      "body": "{{name}}, join your team on {{company}} to start collaborating.",
      "ctaText": "Accept invitation",
      "ctaLink": null,
      "footer": "Sent by {{company}} via Blue."
    }
  }
}

List templates

Use the emailTemplates query to page through the templates for the context organization, optionally filtered by type. Like emailTemplate, it requires only organization membership.

query EmailTemplates {
  emailTemplates(filter: { type: INVITATION }, skip: 0, take: 20) {
    items {
      id
      type
      enabled
      subject
    }
    pageInfo {
      totalItems
      totalPages
      page
      perPage
      hasNextPage
      hasPreviousPage
    }
  }
}

{
  "data": {
    "emailTemplates": {
      "items": [
        {
          "id": "clm4n8qwx000008l0g4oxdqn7",
          "type": "INVITATION",
          "enabled": true,
          "subject": "You've been invited to {{company}}"
        }
      ],
      "pageInfo": {
        "totalItems": 1,
        "totalPages": 1,
        "page": 1,
        "perPage": 20,
        "hasNextPage": false,
        "hasPreviousPage": false
      }
    }
  }
}

Arguments

EmailTemplateFilterInput

The EmailTemplate type

The EmailTemplatePagination type returned by emailTemplates has the standard shape: items (a list of EmailTemplate) and pageInfo (a PageInfo).

Errors

Permissions

The two read queries and the four write operations have different access rules:

• Writes — createEmailTemplate, updateEmailTemplate, deleteEmailTemplate, and sendTestEmail require that you are an OWNER or ADMIN of the organization and that the organization has the white_label feature. For update, delete, and sendTestEmail the organization is resolved from the template’s own id; for create it is the companyId you pass.
• Reads — emailTemplate and emailTemplates require only that you are a member of the context organization (any CompanyUser row). They do not require white_label, so non-white-label members can inspect whether overrides exist.

White-label is bundled with the Pro plan — there is no standalone white-label SKU or subscription to manage through the API. Billing flows through the standard billing portal.

Related

• Custom Domains & Email overview
• Custom Domains
• SMTP Credentials
• Authentication