All Docs
FeaturesagentOS Direct DebitUpdated March 13, 2026

Mandate Invite Emails

Mandate Invite Emails

The Direct Debit service supports sending a branded invitation email to a tenant, giving them a secure, tokenised link to complete their Direct Debit mandate form. This page covers how the invite flow works, what the email contains, how the token lifecycle is tracked, and how to resend an invite.

Overview

When a letting agent is ready to collect a Direct Debit mandate from a tenant, they trigger an invitation. The service generates a unique form token, stores it against the mandate, and dispatches an email to the tenant via an Inngest background job.

The tenant receives an email with everything they need to get started. Clicking the link takes them directly to their pre-scoped mandate form.

Email Contents

Each mandate invitation email includes:

FieldDescription
Form linkUnique, tokenised URL to the tenant's mandate form
Agent nameThe letting agent's display name
Agent logoThe agent's branded logo
DD amountThe Direct Debit amount to be collected
FrequencyPayment frequency (e.g. monthly)
Expiry noticeA clear indication of when the link expires

Emails are rendered using the platform's existing email template system.

Token Lifecycle

Each invitation is backed by a mandate_form_tokens record. The service tracks the following statuses on that record:

StatusMeaning
sentThe invitation email has been dispatched to the tenant
openedThe tenant clicked the link and loaded the mandate form
expiredThe token passed its expiry time without the mandate being completed

Only one active token exists per mandate at any given time. Resending an invite invalidates the previous token before issuing a new one.

Resending an Invite

If a tenant has not acted on an invitation (e.g. the link has expired, or the email was missed), an agent can trigger a resend. The resend flow:

  1. Invalidates the existing token for the mandate.
  2. Generates a new token with a fresh expiry.
  3. Dispatches a new invitation email via the Inngest job.

This ensures tenants always work from a single, current link and prevents confusion from multiple outstanding invitations.

tRPC Mutation

The invite send and resend operations are exposed as a tRPC mutation. Consumers (such as agentOS) call this mutation to trigger the invite flow.

Send / Resend Invite

Mutation: mandate.sendInvite

Input

{
  mandateId: string   // The ID of the mandate to invite the tenant for
}

Behaviour

  • If no prior invite exists, a new token is created and the email is dispatched.
  • If a prior token exists (regardless of status), it is invalidated and a new token is generated before dispatch.

Response

{
  success: boolean
  tokenId: string     // The ID of the newly created form token
}

Background Job

Email dispatch is handled asynchronously by an Inngest job. This means the tRPC mutation returns quickly after enqueuing the job — the actual email send happens out-of-band, keeping the API responsive even under load.

If the email job fails, it will be retried according to the platform's standard Inngest retry policy.

Related