Welcome to our newsletter.
',\n text: 'Hello! Welcome to our newsletter.',\n },\n});\n\n// Update campaign\nconst updated = await client.campaigns.update(101, {\n subject: 'Updated Subject Line',\n});\n\n// Schedule campaign\nawait client.campaigns.schedule(101, {\n scheduled_at: '2024-12-31T10:00:00Z',\n});\n\n// Send campaign immediately\nawait client.campaigns.send(101);\n\n// Pause campaign\nawait client.campaigns.pause(101);\n\n// Resume campaign\nawait client.campaigns.resume(101);\n\n// Cancel campaign\nawait client.campaigns.cancel(101);\n\n// Get campaign statistics\nconst stats = await client.campaigns.getStatistics(101);\n\n// Send test email\nawait client.campaigns.sendTest(101, ['test@example.com']);\n```\n\n## Multi-Tenant Operations\n\nFor parent accounts managing child accounts, you can specify an `accountId` option:\n\n```typescript\n// Access child account data\nconst childContacts = await client.contacts.list(\n { status: 'active' },\n { accountId: 456 } // Child account ID\n);\n\n// Create resource in child account\nconst newContact = await client.contacts.create(\n {\n email: 'new@example.com',\n first_name: 'John',\n },\n { accountId: 456 }\n);\n```\n\n## Error Handling\n\nThe SDK provides detailed error types for better error handling:\n\n```typescript\nimport {\n CakemailError,\n CakemailAPIError,\n CakemailAuthError,\n CakemailNetworkError,\n CakemailValidationError,\n} from '@cakemail-org/cakemail-sdk';\n\ntry {\n const contact = await client.contacts.get(999);\n} catch (error) {\n if (error instanceof CakemailAPIError) {\n console.error('API Error:', error.getUserFriendlyMessage());\n console.error('Status Code:', error.statusCode);\n console.error('Response:', error.responseBody);\n } else if (error instanceof CakemailAuthError) {\n console.error('Authentication failed:', error.message);\n } else if (error instanceof CakemailNetworkError) {\n console.error('Network error:', error.message);\n } else if (error instanceof CakemailValidationError) {\n console.error('Validation error:', error.message);\n }\n}\n```\n\n### User-Friendly Error Messages\n\nAPI errors include user-friendly messages via `getUserFriendlyMessage()`:\n\n```typescript\ntry {\n await client.contacts.create({ email: 'invalid-email' });\n} catch (error) {\n if (error instanceof CakemailAPIError) {\n // Shows: \"Invalid request: Invalid email format. Please check your parameters.\"\n console.error(error.getUserFriendlyMessage());\n }\n}\n```\n\n## Authentication\n\n### Automatic Token Management\n\nThe SDK automatically handles OAuth 2.0 token lifecycle:\n\n- Authenticates on first API request\n- Caches access tokens\n- Refreshes tokens before expiration (5-minute buffer)\n- Retries failed requests after token refresh\n\n### Manual Authentication\n\n```typescript\n// Explicitly authenticate (optional)\nawait client.authenticate();\n\n// Get token information\nconst tokenInfo = client.getTokenInfo();\nconsole.log('Token valid:', tokenInfo.isValid);\nconsole.log('Expires at:', new Date(tokenInfo.expiresAt!));\n\n// Clear cached token (forces re-authentication)\nclient.clearAuthCache();\n```\n\n## Retry Logic\n\nThe SDK automatically retries failed requests with exponential backoff:\n\n- Network errors: Retries automatically\n- 5xx server errors: Retries automatically\n- 401 errors: Refreshes token and retries once\n- Max retries: 3 attempts (configurable)\n- Backoff: 1s, 2s, 4s, 8s (max 10s)\n\n## TypeScript Support\n\nThe SDK is written in TypeScript and includes comprehensive type definitions:\n\n```typescript\nimport {\n Account,\n Contact,\n List,\n Campaign,\n CreateContactRequest,\n UpdateContactRequest,\n ContactStatus,\n CampaignStatus,\n} from '@cakemail-org/cakemail-sdk';\n\nconst contact: Contact = await client.contacts.get(123);\n\nconst createRequest: CreateContactRequest = {\n email: 'new@example.com',\n first_name: 'John',\n status: ContactStatus.Active,\n};\n```\n\n## Command-Line Interface\n\nFor quick testing, automation scripts, and terminal access, the [Cakemail CLI](https://github.com/cakemail/cakemail-cli) is also available:\n\n**Installation:**\n```bash\n# via Homebrew (macOS/Linux)\nbrew tap cakemail/cakemail\nbrew install cakemail-cli\n\n# via npm\nnpm install -g @cakemail-org/cakemail-cli\n\n# via npx (no installation)\nnpx @cakemail-org/cakemail-cli --help\n```\n\n**Example usage:**\n```bash\ncakemail campaigns list\ncakemail contacts create --email user@example.com --first-name John\ncakemail campaigns send --id 123\n```\n\nThe CLI uses this SDK internally and is ideal for:\n- Quick testing and debugging\n- DevOps automation and CI/CD pipelines\n- Non-developer users (marketers, operations teams)\n- Scripting and batch operations\n\nSee the [CLI documentation](https://github.com/cakemail/cakemail-cli) for complete details.\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Generate coverage report\nnpm run test:coverage\n\n# Lint code\nnpm run lint\n```\n\n## License\n\nMIT\n\n## Related Projects\n\n- [Cakemail CLI](https://github.com/cakemail/cakemail-cli) - Command-line interface for Cakemail\n- [Cakemail n8n Node](https://github.com/cakemail/cakemail-n8n-nodes) - n8n workflow automation integration\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: https://github.com/cakemail/cakemail-sdk/issues\n- Documentation: https://docs.cakemail.com\n","readmeFilename":"README.md"}