Skip to content
Skip to main content

Reduce churn by catching dead accounts

Last updated:

Nobody churns the day their grant expires. They churn six weeks later, after their mailbox quietly stopped syncing, your product quietly stopped working, and they quietly stopped opening it. By the time anyone notices, the story they tell is that your product broke.

An expired grant is the cheapest churn signal you will ever get, and it arrives the moment the problem starts. A workflow on grant.expired turns it into a reconnect email while the user still remembers what your product does.

A reconnect email explaining the account connection expired, with the account address, provider, and a reconnect button

Why do expired grants cause churn?

Section titled “Why do expired grants cause churn?”

Because the failure is invisible to the user and silent in your product. Credentials stop working after a password change, a revoked permission, or an expired OAuth token, and none of those feel to the user like an event that should break an integration.

What they see is data that stopped updating. What they conclude is that your product is unreliable. The gap between the grant expiring and the user noticing is where the relationship is lost.

A reconnect email costs one send. Winning the same user back after they cancel costs a sales cycle.

Which events should I watch?

Section titled “Which events should I watch?”

Two carry churn signal, and they mean different things. The grant lifecycle diagram shows where each one fires.

EventCodeWhat it meansUrgency
grant.expired25009Credentials stopped working, the user hasn’t leftHigh. Recoverable.
grant.deleted25013The grant was removed by a Delete Grant requestLower, but tells you why

Grant lifecycle and notifications

An expired grant keeps its ID, data, and object IDs until the user re-authenticates. Deleting a grant is permanent, and the user's next sign-in creates a new grant ID. Changing a valid grant's settings also sends grant.updated.
Diagram as text
  • States:
    • valid: API requests and notifications work.
    • invalid: Grant, data, and object IDs are kept.
    • Deleted: Next sign-in creates a new grant ID.
  • Transitions:

grant.expired is the one that matters. The user hasn’t decided anything, something broke, and a single email recovers them. Treat it as an incident rather than a notification.

grant.deleted is a departure. The email won’t usually bring them back, but it confirms the disconnection was deliberate and gives someone who didn’t expect it a way to respond. It also separates accidental disconnections from real cancellations in your own data.

Also available: grant.updated carries reauthentication_flag, which tells you when a user reconnected. Use it to close the loop and suppress follow-ups, not to send more email.

Why do these need a sender address?

Section titled “Why do these need a sender address?”

You can’t send email through a mailbox that has stopped working. grant.expired and grant.deleted both require a from object, which routes the message through transactional send on a verified domain rather than through the grant.

Omitting it returns 400 This event type requires transactional send. Please provide a sender email address. That restriction is the whole point: a workflow without from sends through the grant that triggered it, which for an expired credential is a contradiction.

curl -X POST 'https://api.us.nylas.com/v3/workflows' \
  -H "Authorization: Bearer $NYLAS_API_KEY" -H 'Content-Type: application/json' \
  -d '{
    "name": "Reconnect prompt",
    "trigger_event": "grant.expired",
    "template_id": "<TEMPLATE_ID>",
    "delay": 0,
    "is_enabled": true,
    "from": { "email": "[email protected]", "name": "Your Company" }
  }'

Register and verify the sending domain first through Managing domains, or the workflow has nowhere to send from.

How do I avoid emailing people who already fixed it?

Section titled “How do I avoid emailing people who already fixed it?”

Set a delay, then check before you send. delay is in minutes, and a short one covers the common case where the user reconnects within the same session because they were already in your product when it broke.

A delay alone isn’t a suppression list. A workflow can’t check the grant’s current state, so the send happens whether or not the grant recovered. For anything beyond a short delay, subscribe to the grant.expired webhook, record the expiry in your own system, and send from your code once you have confirmed the grant is still invalid.

The rule of thumb: use the workflow when one prompt is enough, and move to a webhook when you want a sequence. A reconnect campaign that messages on day 1, day 3, and day 7 needs state that workflows don’t have.

What should the reconnect email say?

Section titled “What should the reconnect email say?”

Lead with the consequence, not the event. “Your account connection has expired” means nothing on its own. “We can no longer sync your mailbox, and nothing will update until you reconnect” tells the user why they should care.

Four things earn their place:

Which account. {{email}} is the only field that identifies which of the user’s connections broke, and a user with two mailboxes can’t act without it.

Why it usually happens. A password change, a revoked permission, or an expired token. Naming the likely cause stops the user assuming your product is broken, which is the belief that leads to churn.

What stops working. Be specific about the feature they use. Generic language about syncing doesn’t create urgency.

One button. Point at a page you control that starts a fresh OAuth flow. Never embed a pre-signed link, because it will have expired by the time someone opens a four-day-old email.

Put grant_id, integration_id, and code in small footer text. When the user forwards the email to support instead of clicking the button, that footer saves a round of questions.

The complete template

Section titled “The complete template”

This guards every field, so it renders on a payload carrying nothing but grant_id.

The grant.expired payload doesn’t include the time the grant expired. grant_updated_at is the last successful update to the grant before it expired, which can be days earlier, so the template doesn’t show it as an expiry date.

Render both with POST /v3/templates/render before enabling their workflows. A reconnect email that fails to render sends nothing and reports nothing, which converts a recoverable account straight into a lost one.

Test without breaking a real account

Section titled “Test without breaking a real account”

Create a throwaway grant on an account you control, attach the workflow, then revoke the app’s access from the provider’s security settings. Google revocations happen at myaccount.google.com/permissions. Don’t test by deleting a grant you still need, because deletion can’t be undone.

Two behaviours are worth confirming on that disposable grant. Grant payloads carry no participants array and no recipient object, so the address should be the grant’s own email, which matters most for grant.deleted where the mailbox may already be gone. And the delay between credentials failing and grant.expired firing isn’t documented, so measure it before promising anyone a response time.

What’s next

Section titled “What’s next”