API v3 Grant (Connected Account) Clean Up Flow

Account Cleanup:

Use the following guidance to identify the current state of your grants (Account and Billing) and determine which API endpoints to call in order to remove unnecessary grants before the next billing cycle.

Note: Billing is based on the maximum number of connected grants during the previous month.

• Billing Status Reference:

Managing Grant Deletion to Avoid Next Month’s Billing

To prevent a grant from contributing to the next month’s billing, you must delete the grant before the end of the current month (GMT time).

Important: Deleting a grant stops it from counting toward future billing cycles, but it will still count for the month it was connected.

Deleting a Grant

Use the Delete Grant API to remove a grant. This ensures it is excluded from billing in the following month.

Checking Grant Status

To review the current state of all grants, use the List Grants API.

If you're subscribed to the grant.expired webhook, using the endpoint above may not be necessary.

Recommended Workflow

The following flow can be adapted to fit your specific business logic:

1. Monitor Expired Grants
   Subscribe to the grant.expired webhook to detect when a grant becomes invalid.

2. Prompt for Re-authentication
   Notify the user to re-authenticate their grant.

3. Grace Period Evaluation
   If the user does not re-authenticate within a set period (customizable to your business needs):

   • Check your internal records to determine if the user is still active.

   • If the user has churned or no longer requires Nylas services, proceed to delete the grant via the API.

Additional Notes

• Grants: Used in api docs
• Connected Accounts: Used in billing/invoices

• A deleted grant will not roll into the next billing cycle

• If a user re-authenticates after a grant is deleted, a new grant ID will be issued, but the underlying object IDs (e.g., threads, messages) will remain the same.

Updated April 29, 2025 14:15