Best practices: handling invalid, stopped or cancelled accounts

How to handle accounts that have stopped or gone invalid.

1. Recommended: Ensure you subscribe to webhooks account.invalid
   - Else poll the account endpoint every 30 min to determine if sync_state = invalid
2. Additionally - especially with non-read scopes such as email.send
   If you receive 401 or 403 on the /send endpoint re-authenticate
   If you receive a 403 on any endpoint that is NOT /send ensure the billing_state = paid via the /account endpoint
3. Prompt: The customer to re-authenticate
4. Ensure: You delete old tokens using /revoke-all - while passing the most recent token in keep_access_token

How to handle accounts that wish to cancel / recover cancelled accounts.

1. Use the downgrade endpoint - cancelled accounts will be delete after 3 days
2. If account wishes to reconnect
3. Check if the token state is still valid via the /token-info endpoint
4. If valid, hit /upgrade - this removes the need for customers to authenticate again
5. If invalid or 404 (token deleted) then  prompt for authentication
   1. Ensure you delete old tokens using /revoke-all  - while passing the most recent token in keep_access_token

Resources

Webhook best practices

How to determine if an account is stopped

I changed my password but didn't received an 'account.invalid' webhook and the account is still running.

Updated November 20, 2023 10:10