📝 docs(lib): remove gmail query syntax and troubleshooting

- remove gmail query syntax
- remove performance & limits
- remove logging
- remove security considerations
- remove troubleshooting
- remove see also
This commit is contained in:
Jeremiah Russell
2025-10-17 17:00:18 +01:00
committed by Jeremiah Russell
parent a5ea370af2
commit 4aa47173c4

View File

@@ -231,105 +231,3 @@ async fn main() -> cull_gmail::Result<()> {
} }
``` ```
## Gmail Query Syntax
The library supports Gmail's search syntax for message queries:
```rust path=null start=null
// Date-based queries
client.set_query("older_than:1y"); // Older than 1 year
client.set_query("newer_than:30d"); // Newer than 30 days
client.set_query("after:2023/1/1"); // After specific date
// Label-based queries
client.set_query("label:promotions"); // Has promotions label
client.set_query("-label:important"); // Does NOT have important label
// Content queries
client.set_query("subject:newsletter"); // Subject contains "newsletter"
client.set_query("from:noreply@example.com"); // From specific sender
// Combined queries
client.set_query("label:promotions older_than:6m -is:starred");
```
## Performance & Limits
### Pagination
- Default page size: 200 messages
- Use `client.set_max_results(n)` to adjust
- Use `client.get_messages(0)` to get all pages
- Use `client.get_messages(n)` to limit to n pages
### Rate Limits
- The library uses the official `google-gmail1` crate
- Built-in retry logic for transient errors
- Respects Gmail API quotas and limits
### Batch Operations
- Batch delete/trash operations are more efficient than individual calls
- Operations are atomic - either all succeed or all fail
## Logging
The library uses the `log` crate for logging:
```rust path=null start=null
use env_logger;
// Initialize logging
env_logger::init();
# Set log level via environment variable
# RUST_LOG=cull_gmail=debug cargo run
```
Log levels:
- `error`: Critical errors
- `warn`: Warnings (e.g., missing labels, dry-run mode)
- `info`: General information (e.g., message subjects, action results)
- `debug`: Detailed operation info
- `trace`: Very detailed debugging info
## Security Considerations
### OAuth2 Token Storage
- Tokens are stored in `~/.cull-gmail/gmail1` by default
- Tokens are automatically refreshed when expired
- Revoke access in [Google Account settings](https://myaccount.google.com/permissions)
### Required Scopes
The library requires the `https://mail.google.com/` scope for full Gmail access.
### Credential File Security
- Store credential files securely (not in version control)
- Use restrictive file permissions (600)
- Consider using environment variables in production
## Troubleshooting
### Authentication Issues
1. Verify credential file path and format
2. Check OAuth2 client is configured for "Desktop Application"
3. Ensure redirect URI matches configuration
4. Clear token cache: `rm -rf ~/.cull-gmail/gmail1`
### No Messages Found
1. Verify label names exist: `client.show_label()`
2. Test query syntax in Gmail web interface
3. Check for typos in label names or query strings
### Rate Limiting
1. Reduce page size: `client.set_max_results(100)`
2. Add delays between operations
3. Check [Gmail API quotas](https://developers.google.com/gmail/api/reference/quota)
## See Also
- [CLI Documentation](main.md) - Complete guide to the command-line interface
- [Examples Directory](../examples/) - Additional code examples and sample configurations
- [API Documentation](https://docs.rs/cull-gmail) - Generated API reference
- [Repository](https://github.com/jerus-org/cull-gmail) - Source code and issue tracking