diff --git a/.github/README.md b/.github/README.md index 872a315..3fa5803 100644 --- a/.github/README.md +++ b/.github/README.md @@ -1,4 +1,4 @@ -![ByteSend](./apps/web/public/nameplate.png) +![ByteSend](../apps/web/public/nameplate.png) **Open-source email infrastructure that works.** REST API, SMTP relay, campaigns, contact management, and real-time webhooks self-hosted or managed on [bytesend.cloud](https://bytesend.cloud). diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index dab5119..b07b6d2 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -11,6 +11,9 @@ # name: "CodeQL Advanced" +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" + on: push: branches: [ "main", "develop" ] @@ -59,7 +62,7 @@ jobs: # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 # Add any setup steps before running the `github/codeql-action/init` action. # This includes steps like installing compilers or runtimes (`actions/setup-node` diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 69317a2..fb0a9e9 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -1,5 +1,8 @@ name: Publish Docker +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" + on: push: branches: @@ -36,25 +39,28 @@ jobs: context: ./apps/smtp-server steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v5 with: fetch-depth: 0 ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.branch || github.ref }} - name: Set up QEMU - uses: docker/setup-qemu-action@v3 + uses: docker/setup-qemu-action@v4 - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 + uses: docker/setup-buildx-action@v4 - name: Login to DockerHub - uses: docker/login-action@v3 + uses: docker/login-action@v4 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v4 + - name: Login to GitHub Container Registry - uses: docker/login-action@v3 + uses: docker/login-action@v4 with: registry: ghcr.io username: ${{ github.repository_owner }} @@ -93,9 +99,9 @@ jobs: IMAGE_TAG_ARGS="" for TAG in $TAGS; do IMAGE_TAG_ARGS="$IMAGE_TAG_ARGS -t bytesend/$APP-$BUILD_PLATFORM:$TAG -t ghcr.io/bytesend/$APP-$BUILD_PLATFORM:$TAG" - # Clean up any existing platform-specific tags to avoid manifest conflicts on re-run - docker manifest rm bytesend/$APP-$BUILD_PLATFORM:$TAG 2>/dev/null || true - docker manifest rm ghcr.io/bytesend/$APP-$BUILD_PLATFORM:$TAG 2>/dev/null || true + # Remove remote tags (single image or manifest list) so re-runs can safely republish. + docker buildx imagetools rm bytesend/$APP-$BUILD_PLATFORM:$TAG 2>/dev/null || true + docker buildx imagetools rm ghcr.io/bytesend/$APP-$BUILD_PLATFORM:$TAG 2>/dev/null || true done docker buildx build \ @@ -117,19 +123,19 @@ jobs: needs: build_and_publish_platform_containers steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 with: fetch-depth: 0 ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.branch || github.ref }} - name: Login to DockerHub - uses: docker/login-action@v3 + uses: docker/login-action@v4 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Login to GitHub Container Registry - uses: docker/login-action@v3 + uses: docker/login-action@v4 with: registry: ghcr.io username: ${{ github.repository_owner }} @@ -157,10 +163,10 @@ jobs: for APP_NAME in bytesend smtp-proxy; do for TAG in $TAGS; do - # Clean up any existing manifests (allows re-running without failures) - docker manifest rm bytesend/$APP_NAME:$TAG 2>/dev/null || true - docker manifest rm bytesend/$APP_NAME-amd64:$TAG 2>/dev/null || true - docker manifest rm bytesend/$APP_NAME-arm64:$TAG 2>/dev/null || true + # Remove remote tags/manifests first so reruns are idempotent. + docker buildx imagetools rm bytesend/$APP_NAME:$TAG 2>/dev/null || true + docker buildx imagetools rm bytesend/$APP_NAME-amd64:$TAG 2>/dev/null || true + docker buildx imagetools rm bytesend/$APP_NAME-arm64:$TAG 2>/dev/null || true docker manifest create \ bytesend/$APP_NAME:$TAG \ @@ -193,10 +199,10 @@ jobs: for APP_NAME in bytesend smtp-proxy; do for TAG in $TAGS; do - # Clean up any existing manifests (allows re-running without failures) - docker manifest rm ghcr.io/bytesend/$APP_NAME:$TAG 2>/dev/null || true - docker manifest rm ghcr.io/bytesend/$APP_NAME-amd64:$TAG 2>/dev/null || true - docker manifest rm ghcr.io/bytesend/$APP_NAME-arm64:$TAG 2>/dev/null || true + # Remove remote tags/manifests first so reruns are idempotent. + docker buildx imagetools rm ghcr.io/bytesend/$APP_NAME:$TAG 2>/dev/null || true + docker buildx imagetools rm ghcr.io/bytesend/$APP_NAME-amd64:$TAG 2>/dev/null || true + docker buildx imagetools rm ghcr.io/bytesend/$APP_NAME-arm64:$TAG 2>/dev/null || true docker manifest create \ ghcr.io/bytesend/$APP_NAME:$TAG \ diff --git a/.github/workflows/issue-summary.yml b/.github/workflows/issue-summary.yml index badb28c..29f7e30 100644 --- a/.github/workflows/issue-summary.yml +++ b/.github/workflows/issue-summary.yml @@ -1,5 +1,8 @@ name: Summarize new issues +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" + on: issues: types: [opened] @@ -14,7 +17,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Run AI inference id: inference diff --git a/.github/workflows/npm-release.yml b/.github/workflows/npm-release.yml index 158bf3e..fd38065 100644 --- a/.github/workflows/npm-release.yml +++ b/.github/workflows/npm-release.yml @@ -1,12 +1,14 @@ -name: Release JS Packages +name: Relase Node SDK + +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" on: push: branches: - main paths: - - "packages/sdk/**" # Trigger only changes in packages - - ".github/workflows/npm-release.yml" + - "packages/sdk/**" workflow_dispatch: permissions: @@ -22,7 +24,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Set up Node.js 20.x uses: actions/setup-node@v4 @@ -43,18 +45,14 @@ jobs: - name: Install dependencies run: pnpm install --frozen-lockfile - - name: Publish with Trusted Publishing (OIDC) - if: ${{ secrets.NPM_TOKEN == '' }} - working-directory: packages/sdk - run: | - pnpm run build - npm publish --access public --no-git-checks --provenance - - - name: Publish with NPM token - if: ${{ secrets.NPM_TOKEN != '' }} + - name: Publish package working-directory: packages/sdk env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} run: | pnpm run build - npm publish --access public --no-git-checks \ No newline at end of file + if [ -n "$NODE_AUTH_TOKEN" ]; then + npm publish --access public --no-git-checks + else + npm publish --access public --no-git-checks --provenance + fi \ No newline at end of file diff --git a/.github/workflows/pypi-release.yml b/.github/workflows/pypi-release.yml new file mode 100644 index 0000000..6cd5bcc --- /dev/null +++ b/.github/workflows/pypi-release.yml @@ -0,0 +1,49 @@ +name: Relase Python SDK + +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" + +on: + push: + branches: + - main + paths: + - "packages/python-sdk/**" + workflow_dispatch: + +permissions: + id-token: write + contents: read + +concurrency: ${{ github.workflow }}-${{ github.ref }} + +jobs: + release: + runs-on: ubuntu-latest + environment: pypi + defaults: + run: + working-directory: packages/python-sdk + steps: + - uses: actions/checkout@v5 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - uses: snok/install-poetry@v1 + with: + version: "1.8.2" + virtualenvs-create: false + + - name: Build package with Poetry + run: poetry build --no-interaction + + - name: List contents of dist + run: ls -la dist + + - name: Publish to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 + with: + packages-dir: packages/python-sdk/dist \ No newline at end of file diff --git a/.github/workflows/stale-cleanup.yml b/.github/workflows/stale-cleanup.yml index d64b3bd..7c1398e 100644 --- a/.github/workflows/stale-cleanup.yml +++ b/.github/workflows/stale-cleanup.yml @@ -5,6 +5,9 @@ # https://github.com/actions/stale name: Mark stale issues and pull requests +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" + on: schedule: - cron: '23 13 * * *' diff --git a/.github/workflows/website-test.yml b/.github/workflows/website-test.yml index f4f079b..c4304c1 100644 --- a/.github/workflows/website-test.yml +++ b/.github/workflows/website-test.yml @@ -1,5 +1,8 @@ name: Website Tests +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" + on: pull_request: paths: @@ -55,7 +58,7 @@ jobs: --health-retries 20 steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v5 - name: Setup pnpm uses: pnpm/action-setup@v4 diff --git a/CHANGELOG.md b/CHANGELOG.md index f7550b0..7298a90 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,7 +40,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Issue summary workflow** — added `.github/workflows/issue-summary.yml` to automatically summarize newly opened issues - **Stale cleanup workflow** — added `.github/workflows/stale-cleanup.yml` to clean up inactive issues and pull requests - **CodeQL workflow** — introduced `.github/workflows/codeql.yml` and enabled `develop` branch triggers -- **JavaScript SDK release workflow** — added `.github/workflows/npm-release.yml` to build and publish the `bytesend-js` package from `packages/sdk` on pushes to `main` and manual dispatch +- **JavaScript SDK release workflow** — added `.github/workflows/npm-release.yml` to build and publish the `bytesend-js` package from `packages/sdk` changes on `main` (plus manual dispatch) +- **Python SDK release workflow** — added `.github/workflows/pypi-release.yml` to build and publish the `bytesend-python` package from `packages/python-sdk` on pushes to `main` and manual dispatch #### Community / Governance - **Repository security policy** — added `.github/SECURITY.md` with supported versions, private reporting process, and response expectations @@ -73,6 +74,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **SMTP docs refreshed for monorepo paths** — clone/build/deployment documentation now references `NodeByteLTD/ByteSend` and `apps/smtp-server` paths throughout - **SMTP quickstart clarified** — get-started docs now direct users to use their configured SMTP username (default `bytesend`) rather than implying only a fixed username - **Core docs/readme refresh** — updated main README and docs navigation/content pages for current monorepo structure and self-hosting guidance (`apps/docs/README.md`, `apps/docs/docs.json`, local/docker/self-hosting guide pages) +- **Feature docs expansion** — added new guides for GitHub OAuth, API authentication, plans/pricing, plan management, admin operations, and notification providers (`apps/docs/guides/*`) +- **Mintlify branding refresh** — updated `apps/docs/docs.json` theme colors/navigation and expanded `apps/docs/introduction.mdx` to surface new billing, alerting, and auth capabilities #### References - **Internal references expanded** — added `.references/README.md`, `smtp-auth-and-operations.md`, `release-playbook.md`, and `repository-governance.md` @@ -87,10 +90,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Website test workflow tuning** — adjusted website test workflow behavior - **Docker publish workflow update** — updated `.github/workflows/docker-publish.yml` - **Docker manifest recreation safety** — docker publish now removes existing manifests before create, preventing rerun failures on previously published tags +- **Docker remote tag cleanup** — docker publish now removes pre-existing remote tags/manifests with `docker buildx imagetools rm` before publishing platform images/manifests, avoiding `is a manifest list` rerun failures - **Website tests pnpm version alignment** — removed hardcoded pnpm version from `.github/workflows/website-test.yml` so CI uses the repository `packageManager` version (`pnpm@9.0.0`) - **Docker publish tag strategy hardening** — `.github/workflows/docker-publish.yml` now publishes ref-aware tags (`latest`, `develop`, version tag, and commit SHA) with matching multi-arch manifests - **Manual Docker publish branch support** — wired `workflow_dispatch` branch input into checkout and tag resolution so manual runs build/publish the selected branch - **Labeler rules refresh** — updated `.github/labeler.yml` to align automated PR labeling with the current repository structure +- **Actions runtime forward-compatibility** — added `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true` across workflows to avoid Node 20 JavaScript action deprecation breakage ### Fixed diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 62a2bcc..daad292 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -3,14 +3,14 @@ "theme": "mint", "name": "ByteSend", "colors": { - "primary": "#144B90", - "light": "#DBEAFE", - "dark": "#4395F9" + "primary": "#0066CC", + "light": "#E6F2FF", + "dark": "#3D9FFF" }, "background": { "color": { - "light": "#F5F7FA", - "dark": "#101120" + "light": "#F8F9FB", + "dark": "#0A0E1A" } }, "fonts": { @@ -33,6 +33,7 @@ "introduction", "get-started/smtp", "get-started/nodejs", + "get-started/python", "get-started/local", "get-started/set-up-docker" ] @@ -59,7 +60,30 @@ "tab": "Guides", "groups": [ { - "group": "User Guides", + "group": "Account & Authentication", + "pages": [ + "guides/github-oauth", + "guides/api-authentication" + ] + }, + { + "group": "Account & Billing", + "pages": [ + "guides/plans-and-pricing", + "guides/plan-management", + "guides/admin-operations" + ] + }, + { + "group": "Notifications & Alerts", + "pages": [ + "guides/notification-providers", + "guides/discord-notifications", + "guides/slack-notifications" + ] + }, + { + "group": "Integration Guides", "pages": [ "guides/webhooks", "guides/double-opt-in", diff --git a/apps/docs/guides/admin-operations.mdx b/apps/docs/guides/admin-operations.mdx new file mode 100644 index 0000000..d4a80d8 --- /dev/null +++ b/apps/docs/guides/admin-operations.mdx @@ -0,0 +1,325 @@ +--- +title: Admin Operations & Billing +description: "Manage billing operations and admin settings for your ByteSend account" +icon: shield-admin +--- + +## Overview + +Admin operations allow you to manage billing, team permissions, and advanced account settings. These features are only available to users with Admin role. + +## Admin Capabilities + +### Account Administration + +**Team Member Management**: +- Add and remove team members +- Assign and modify roles (Admin, Editor, Viewer) +- View member activity and last login information +- Manage pending invitations + +**Plan & Billing Management**: +- View current plan and usage +- Upgrade or downgrade plans +- Access billing history and invoices +- Update payment methods +- Set up billing notifications + +**Workspace Settings**: +- Configure account name and branding +- Manage API keys +- Set security policies +- Configure notification channels + +## Billing Management + +### Accessing Billing + +1. Log in to [ByteSend Dashboard](https://bytesend.cloud) +2. Navigate to **Settings** → **Billing** +3. View current plan, usage, and invoices + +### Current Plan Information + +The billing dashboard shows: +- **Active Plan**: Your current subscription level +- **Monthly Usage**: Emails sent vs. plan limit +- **Team Members**: Used vs. plan limit +- **Verified Domains**: Used vs. plan limit +- **Renewal Date**: When your next billing cycle begins +- **Cost**: Monthly/annual amount + +### Upgrading Your Plan + +#### Automatic Plan Limits + +Each plan comes with specific limits: + +**Free Plan**: +- 100 emails/month +- 1 domain +- 1 team member +- 7-day history + +**BASIC Plan**: +- 100,000 emails/month +- 12 domains +- 30 team members +- 90-day history + +**LIFETIME Plan**: +- 500,000 emails/month +- 30 domains +- 100 team members +- Unlimited history + +#### When to Upgrade + +You should upgrade when: +- Approaching your monthly email limit +- Need more verified domains +- Adding team members +- Need longer message history + +**To upgrade**: + +1. Go to **Settings** → **Billing** → **Plans** +2. Click **Upgrade Plan** +3. Select your desired plan +4. Review the changes +5. Enter payment details +6. Confirm upgrade +7. Changes take effect immediately + + +If upgrading mid-month to BASIC, remaining months credit to your account. Upgrading to LIFETIME is a flat one-time fee regardless of your billing cycle. + + +### Downgrading Your Plan + + +Downgrading may impact your account if you exceed free tier limits. For example, extra team members will be archived. + + +**To downgrade**: + +1. Go to **Settings** → **Billing** +2. Click **Downgrade Plan** +3. Review what will change +4. Confirm the downgrade +5. Changes take effect at the end of your current billing cycle + +### Managing Payment Methods + +#### Adding a Payment Method + +1. Go to **Settings** → **Billing** → **Payment Methods** +2. Click **Add Payment Method** +3. Select payment type (Credit Card / PayPal) +4. Enter payment details +5. Click **Save** + +#### Changing Default Payment Method + +1. Go to **Settings** → **Billing** → **Payment Methods** +2. Click **Set as Default** next to the desired method +3. Future charges will use this method + +#### Removing Payment Method + +1. Go to **Settings** → **Billing** → **Payment Methods** +2. Click **Remove** next to the method +3. Ensure another method is set as default +4. Method is removed from your account + +#### Failed Payment Recovery + +If a payment fails: +- You'll receive an email notification +- Retry within 5 days to avoid service interruption +- Update your payment method if the card was declined +- Contact support if the issue persists + +### Invoices & Billing History + +#### Viewing Invoices + +1. Go to **Settings** → **Billing** → **Invoices** +2. Click on any invoice to view details +3. View PDF or download for records + +#### Invoice Details + +Each invoice includes: +- Invoice number and date +- Billing period +- Plan and pricing +- Any prorated charges/credits +- Total amount due +- Payment status + +#### Downloading Invoices + +1. Click the invoice you want +2. Click **Download PDF** +3. Invoice is saved to your computer +4. Keep for your records and accounting + +### Tax Information + +#### Adding Tax Details + +1. Go to **Settings** → **Billing** → **Tax** +2. Enter your tax ID or business number +3. Select your country/region +4. Click **Save** + +#### Tax Calculation + +- Tax is applied based on your billing location +- Tax ID may exempt you from VAT/GST +- Tax information appears on your invoices + +## Team Permissions & Roles + +### Admin Role + +**Capabilities**: +- Add/remove team members +- Change member roles +- Access all account settings +- Manage billing and payment methods +- View all team activity +- Create and manage API keys +- Configure notifications + +**Best for**: Account owners, billing contacts, senior team members + +### Editor Role + +**Capabilities**: +- Create and edit campaigns +- Manage email templates +- Verify new domains +- Create webhooks +- View analytics and reports +- Access API with owned keys + +**Restrictions**: Cannot manage team members, billing, or settings + +**Best for**: Team members actively managing emails + +### Viewer Role + +**Capabilities**: +- View campaigns and reports +- View analytics and dashboards +- Read-only access to settings +- Cannot make changes + +**Restrictions**: Cannot send emails, create campaigns, or modify settings + +**Best for**: Stakeholders, clients, observers + +## Security & Compliance + +### Two-Factor Authentication + +For GitHub OAuth users: +- Enable 2FA on your GitHub account +- [GitHub 2FA setup](https://github.com/settings/security) + +### API Key Management + +Admin admins should: +- Regularly audit active API keys +- Revoke old or unused keys +- Use different keys for different environments +- Never share keys with team members +- Store keys in environment variables + +### Audit Logs + +Monitor admin actions: +- Team member additions/removals +- Plan changes +- Payment method updates +- API key generation/revocation + + +Keep audit logs for compliance and security purposes. Consider setting up webhook notifications for admin activity. + + +## Compliance & Business Management + +### Canceling Your Account + +To cancel your ByteSend account: + +1. Go to **Settings** → **Billing** +2. Click **Cancel Account** +3. Select reason for cancellation +4. Confirm the action +5. Your account will be deactivated + + +Account cancellation is permanent. All data will be deleted after 30 days. Export any data you need before canceling. + + +### Data Export + +To export your data before leaving: + +1. Go to **Settings** → **Data** +2. Click **Export All Data** +3. Select data types to export (campaigns, contacts, logs, etc.) +4. Download the exported files (CSV/JSON format) + +### GDPR & Data Privacy + +ByteSend complies with: +- GDPR (General Data Protection Regulation) +- CCPA (California Consumer Privacy Act) +- PIPEDA (Personal Information Protection and Electronic Documents Act) + +For privacy inquiries: +- Contact [privacy@bytesend.cloud](mailto:privacy@bytesend.cloud) +- Submit requests via [Privacy Center](https://bytesend.cloud/privacy) + +## Troubleshooting + +### Payment Declined + +- Verify card details are correct +- Check if card is expired +- Confirm available credit/funds +- Try a different payment method +- Contact your bank to ensure no fraud blocks + +### Can't Access Billing Settings + +- Verify you have Admin role +- Check that your account is active +- Try logging out and back in +- Contact support if issue persists + +### Need an Invoice + +1. Go to **Settings** → **Billing** → **Invoices** +2. Find the invoice you need +3. Click **Download PDF** +4. If invoice is missing, contact support + +### Upgrade Not Applied + +- Confirm payment was successful +- Check that plan change is showing in dashboard +- Try refreshing the page +- Contact support if still not showing + +## Next Steps + +- [Manage your team members](/guides/plan-management) +- [Configure notification alerts](/settings/notifications) +- [Explore your usage](/settings/usage) +- [Contact support](https://discord.gg/xqkqzVRC4S) diff --git a/apps/docs/guides/api-authentication.mdx b/apps/docs/guides/api-authentication.mdx new file mode 100644 index 0000000..a12a59b --- /dev/null +++ b/apps/docs/guides/api-authentication.mdx @@ -0,0 +1,168 @@ +--- +title: API Authentication +description: "Authenticate your API requests to ByteSend with API keys" +icon: lock +--- + +## Overview + +ByteSend API uses **Bearer token authentication** for all API endpoints. You can generate API keys from your dashboard to authenticate requests. + +## Generating an API Key + +### Via Dashboard + +1. Log in to your [ByteSend Dashboard](https://bytesend.cloud) +2. Navigate to **Settings** → **General** +3. Scroll to the **API Keys** section +4. Click **Generate New API Key** +5. Give your key a name (e.g., "Development", "Production") +6. Click **Create** +7. Copy the key immediately — you won't be able to see it again +8. Store it securely (use environment variables, not in version control) + +## Using Your API Key + +### In API Requests + +Include your API key in the `Authorization` header with the `Bearer` scheme: + +```bash +curl -X GET https://bytesend.cloud/api/v1/domains \ + -H "Authorization: Bearer your_api_key_here" +``` + +### In SDK Clients + +#### JavaScript/TypeScript + +```typescript +import { ByteSend } from '@bytesend/js'; + +const client = new ByteSend({ + apiKey: process.env.BYTESEND_API_KEY, +}); + +// Now use the client +const emails = await client.emails.list(); +``` + +#### Python + +```python +from bytesend import ByteSend + +client = ByteSend(api_key=os.getenv('BYTESEND_API_KEY')) + +# Now use the client +emails = client.emails.list() +``` + +## API Key Management + +### Viewing Your Keys + +1. Go to **Settings** → **General** +2. All active API keys are listed with: + - Key name + - Creation date + - Last used date + - Masked key preview + +### Rotating Keys + +To rotate your API key safely: + +1. Generate a new API key in the dashboard +2. Update all applications to use the new key +3. Test that everything works correctly +4. Delete the old key from the dashboard + +### Revoking Keys + +1. Navigate to **Settings** → **General** +2. Find the key you want to revoke +3. Click **Revoke** +4. Confirm the action +5. The key will be immediately invalidated + +## Security Best Practices + +### Protect Your Keys + +- **Never commit API keys to version control** +- Use environment variables to store sensitive keys +- Use different keys for different environments (development, staging, production) +- Rotate keys regularly (every 90 days recommended) +- Revoke keys immediately if compromised + +### Environment Variables + +Create a `.env` file (never commit this): + +```bash +BYTESEND_API_KEY=sk_live_your_key_here +``` + +Load it in your application: + +```typescript +import dotenv from 'dotenv'; +dotenv.config(); + +const apiKey = process.env.BYTESEND_API_KEY; +``` + +### Monitoring Usage + +- Check the "Last used" timestamp to identify unused keys +- Monitor your API usage through the dashboard analytics +- Set up alerts for unusual activity + +## Troubleshooting + +### "Unauthorized" Error + +- Verify the API key is correct and not expired +- Check that the key is included in the `Authorization` header +- Ensure the header format is `Bearer {key}` (with a space) +- Verify the key hasn't been revoked + +### Key Not Working After Generation + +- Make sure you copied the entire key +- Check that there are no extra spaces or characters +- Try revoking and generating a new key + +### Lost or Forgotten Key + +If you lose your API key: + +1. You cannot recover the old key +2. Generate a new API key from the dashboard +3. Update all applications to use the new key +4. Revoke the old key (if known) + +## Rate Limiting + +API keys are subject to rate limits: + +- **Free Plan**: 100 requests/minute +- **BASIC Plan**: 1,000 requests/minute +- **LIFETIME Plan**: 10,000 requests/minute + +Rate limit headers are included in all responses: + +``` +X-RateLimit-Limit: 1000 +X-RateLimit-Remaining: 999 +X-RateLimit-Reset: 1234567890 +``` + +If you exceed the rate limit, you'll receive a `429 Too Many Requests` response. + +## Next Steps + +- [Send your first email](/api-reference/emails/send-email) +- [Explore the full API reference](/api-reference/introduction) +- [View SDK documentation](/get-started/nodejs) diff --git a/apps/docs/guides/discord-notifications.mdx b/apps/docs/guides/discord-notifications.mdx new file mode 100644 index 0000000..360b605 --- /dev/null +++ b/apps/docs/guides/discord-notifications.mdx @@ -0,0 +1,283 @@ +--- +title: Discord Notifications +description: "Receive ByteSend alerts in your Discord server" +icon: discord +--- + +## Overview + +Send real-time ByteSend notifications directly to your Discord server. Get instant alerts about email delivery, team changes, billing updates, and more. + +## Prerequisites + +- Discord server where you have manage permissions +- Admin or Editor role in ByteSend + +## Setting Up Discord Webhooks + +### Step 1: Create a Discord Server (if needed) + +If you don't have a Discord server yet: + +1. Open Discord and click the "+" button +2. Click **Create a New Server** +3. Give your server a name (e.g., "ByteSend Alerts") +4. Click **Create** +5. You now have a server to set up webhooks + +### Step 2: Create a Discord Channel + +1. In your Discord server, click the "+" next to "Text Channels" +2. Enter channel name (e.g., "bytesend-alerts") +3. Set visibility (public or private) +4. Click **Create Channel** + +### Step 3: Create a Webhook + +1. Right-click the channel name +2. Select **Edit Channel** +3. Click **Integrations** in the left sidebar +4. Click **Webhooks** +5. Click **New Webhook** (or **Create Webhook**) +6. Give it a name: "ByteSend Notifications" +7. Click **Copy Webhook URL** +8. Save the URL (you'll need it in the next step) + + +Keep your webhook URL secret! Anyone with this URL can post messages to your channel. Don't share it publicly or commit it to version control. + + +## Connecting ByteSend to Discord + +### In ByteSend Dashboard + +1. Log in to [ByteSend Dashboard](https://bytesend.cloud) +2. Navigate to **Settings** → **Notifications** +3. Find **Discord** under "Notification Channels" +4. Click **Connect** or **Add Discord** +5. Paste your webhook URL +6. Click **Save** + +### Test the Connection + +After connecting: + +1. Click **Test** next to the Discord provider +2. You should receive a test message in your Discord channel +3. The message confirms the connection is working + +If you don't receive the test message: +- Verify the webhook URL is correct +- Check that the bot has permissions in the channel +- Try creating a new webhook + +## Configuring Alert Preferences + +### Choose Alert Types + +1. Go to **Settings** → **Notifications** +2. Click **Configure** next to Discord +3. Check which alert types to receive: + - **Email Delivery**: Send, bounce, delivery alerts + - **Domain Issues**: Verification failures, DNS problems + - **Team Changes**: Member additions, removals, role changes + - **Billing Alerts**: Limit warnings, payment failures + - **Security Events**: Unusual activity, login attempts + - **API Quota**: Rate limit warnings + - **Maintenance**: Platform maintenance notices +4. Click **Save** + +### Set Notification Frequency + +- **Real-time**: Get alerts immediately as they occur +- **Daily Digest**: Receive one message per day summarizing all events +- **Weekly Digest**: Receive one message per week + +Select the frequency that works best for your team. + +## Discord Message Format + +ByteSend sends formatted Discord messages with: + +**Sample Email Alert**: +``` +🚨 Email Failed to Send +Team: Your Team Name +Recipient: user@example.com +Reason: Bounced +Time: May 9, 2024 10:30 AM UTC +``` + +**Sample Team Alert**: +``` +👥 Team Member Added +User: john@example.com +Role: Editor +Added by: admin@example.com +Time: May 9, 2024 2:15 PM UTC +``` + +All messages include: +- Event icon/emoji for quick scanning +- Event details (what happened) +- Timestamp +- Direct link to dashboard (if applicable) + +## Managing Discord Notifications + +### Disable Temporarily + +To pause Discord notifications without disconnecting: + +1. Go to **Settings** → **Notifications** → **Discord** +2. Click **Pause Notifications** +3. Notifications will not be sent to Discord +4. Click **Resume** to re-enable + +### Update Webhook + +If you need to change the webhook URL: + +1. Go to **Settings** → **Notifications** → **Discord** +2. Click **Update Webhook** +3. Paste the new webhook URL +4. Click **Save** +5. Test the connection + +### Disconnect Discord + +To stop sending notifications to Discord: + +1. Go to **Settings** → **Notifications** +2. Click **Disconnect** next to Discord +3. Confirm the action +4. Discord will no longer receive ByteSend notifications + +### Revoke Webhook in Discord + +To prevent ByteSend from posting to a specific channel: + +1. Go to your Discord server settings +2. Navigate to **Integrations** → **Webhooks** +3. Find the "ByteSend Notifications" webhook +4. Click **Delete Webhook** +5. The webhook URL becomes invalid + +## Advanced Configuration + +### Multiple Discord Channels + +To send different alerts to different channels: + +1. Create separate webhooks for different channels +2. In ByteSend, use the "Custom Webhook" option +3. Route different alert types to different endpoints + +### Discord Bot Advanced Setup + +**For team members**: + +If you want team members to receive direct messages: + +1. Create a ByteSend bot user in Discord +2. Send each team member a DM from the bot +3. Bot can post to multiple channels/DMs +4. Requires more complex webhook configuration + + +For simpler setup, use a single channel for all alerts and have team members enable Discord notifications at their preference level. + + +### Filtering Alerts + +To reduce alert noise: + +1. Only enable alert types you care about +2. Use digest mode for low-priority notifications +3. Create separate webhooks for critical vs. informational alerts +4. Use channel topics to document what alerts appear where + +## Troubleshooting + +### Not Receiving Messages + +**Webhook URL incorrect**: +- Copy the URL again from Discord integrations +- Paste it exactly into ByteSend +- Re-test the connection + +**Bot lacks permissions**: +- Right-click the channel +- Select **Edit Channel** +- Go to **Permissions** +- Ensure "ByteSend Notifications" webhook has Send Messages permission +- Add "Send Embeds" permission for formatted messages + +**Channel is archived**: +- Unarchive the channel +- Create a new channel if preferred +- Generate a new webhook for the new channel + +**Webhook deleted in Discord**: +- Your webhook URL is now invalid +- Generate a new webhook URL +- Update it in ByteSend settings +- Test again + +### Too Many Messages + +- Uncheck alert types you don't need in settings +- Switch to digest mode (daily or weekly) +- Create separate webhooks for different alert severities +- Use channel threads to organize related alerts + +### Formatting Issues + +If messages don't look formatted: +- Ensure the bot has embed permissions +- Try deleting and recreating the webhook +- Contact [ByteSend Support](https://discord.gg/xqkqzVRC4S) + +### Webhook URL Expired + +Discord webhooks don't expire, but: +- If you deleted the webhook, create a new one +- If you changed channel permissions, verify settings +- Generate a fresh webhook URL if uncertain + +## Best Practices + +### Organization + +- Create a dedicated `#bytesend-alerts` channel +- Pin important notification configuration +- Archive old alerts periodically +- Document which alerts go to which channels + +### Security + +- Never share your webhook URL publicly +- Don't commit webhook URLs to version control +- Regenerate webhooks if accidentally exposed +- Use a secure password manager to store URLs + +### Team Communication + +- Set channel topic: "Real-time ByteSend notifications" +- Educate team members on alert types +- Establish response procedures for critical alerts +- Review and adjust alert types monthly + +### Integration Tips + +- Combine with other Discord bots (e.g., custom analytics) +- Use Discord threads to discuss specific alerts +- React to alerts with acknowledgment emojis +- Create automation rules for high-priority alerts + +## Next Steps + +- [Return to notification providers](/guides/notification-providers) +- [Set up Slack notifications](/guides/slack-notifications) +- [Manage all notifications settings](/settings/notifications) +- [Join the community Discord](https://discord.gg/xqkqzVRC4S) diff --git a/apps/docs/guides/github-oauth.mdx b/apps/docs/guides/github-oauth.mdx new file mode 100644 index 0000000..3ed13e1 --- /dev/null +++ b/apps/docs/guides/github-oauth.mdx @@ -0,0 +1,132 @@ +--- +title: GitHub OAuth Authentication +description: "Secure your ByteSend account with GitHub OAuth single sign-on" +icon: github +--- + +## Overview + +ByteSend now supports GitHub OAuth authentication, allowing you to securely sign in to your account using your GitHub credentials. This eliminates the need to manage separate passwords for ByteSend. + +## Benefits + +- **Single Sign-On**: Use your GitHub account to quickly access ByteSend +- **Secure**: Leverage GitHub's industry-leading authentication infrastructure +- **Convenient**: No additional passwords to remember +- **Account Linking**: Connect existing ByteSend accounts to GitHub + +## Setting Up GitHub OAuth + +### Initial Login + +1. Visit [ByteSend Dashboard](https://bytesend.cloud) +2. Click **Sign in with GitHub** on the login page +3. You'll be redirected to GitHub's authorization page +4. Review the requested permissions and click **Authorize ByteSend** +5. You'll be redirected back to ByteSend and automatically logged in + +### First Time Setup + +On your first GitHub OAuth login, ByteSend will: +- Create a new account associated with your GitHub profile +- Use your GitHub username as your initial display name +- Set up a default workspace for your account + +### Linking to Existing Account + +If you already have a ByteSend account: + +1. Sign out of your existing account +2. Click **Sign in with GitHub** +3. Complete the GitHub authorization +4. After authorization, you'll be prompted to link your existing account +5. Enter your existing ByteSend email and password to confirm +6. Your accounts will be merged, and you'll use GitHub OAuth going forward + +## Permissions Requested + +ByteSend requests the following GitHub permissions: + +- **Public profile access**: To retrieve your GitHub username and profile picture +- **Email access**: To verify your GitHub email address + +We **never** request access to your repositories or any private GitHub data. + +## Security Considerations + +### Token Storage + +- OAuth tokens are encrypted and stored securely +- Tokens are never exposed in logs or API responses +- Tokens are refreshed automatically when expired + +### Session Management + +- GitHub OAuth sessions automatically expire after a period of inactivity +- You can revoke ByteSend's access at any time from your GitHub settings +- Logging out of ByteSend will not affect your GitHub session + +### Revoking Access + +To revoke ByteSend's access to your GitHub account: + +1. Go to [GitHub Settings → Applications](https://github.com/settings/apps/authorizations) +2. Find "ByteSend" in your authorized applications +3. Click **Revoke** to disconnect the application +4. You'll no longer be able to log in with GitHub until you re-authorize + +## Troubleshooting + +### "Authorization Failed" Error + +- Clear your browser cookies and try again +- Ensure you're using a supported browser (Chrome, Firefox, Safari, Edge) +- Check that your GitHub account has email verification enabled + +### GitHub Authorization Was Denied + +If you click "Cancel" during GitHub authorization: + +1. Return to the ByteSend login page +2. Click **Sign in with GitHub** again +3. Complete the authorization process + +### I Can't Find My Existing Account After Linking + +If your accounts didn't merge as expected: + +1. Contact [ByteSend Support](https://discord.gg/xqkqzVRC4S) +2. We can manually verify and link your accounts +3. Include the email address of both accounts in your support message + +## Best Practices + +### Account Security + +- Keep your GitHub account password secure +- Enable two-factor authentication on your GitHub account for added security +- Regularly review connected applications in your GitHub settings + +### Multiple Teams + +If you have multiple GitHub organizations: + +- Your ByteSend workspace is tied to your personal GitHub account +- Team members can each use their own GitHub accounts to log in +- Workspace access is managed through ByteSend team settings (not GitHub) + +### Switching Authentication Methods + +If you need to use traditional email/password authentication: + +1. Contact [ByteSend Support](https://discord.gg/xqkqzVRC4S) +2. We can reset your authentication method +3. You'll be able to set a traditional password + +## Next Steps + +After logging in with GitHub OAuth: + +- [Set up your first domain](/guides/getting-started) +- [Explore the dashboard](https://bytesend.cloud/dashboard) +- [Join our community](https://discord.gg/xqkqzVRC4S) diff --git a/apps/docs/guides/notification-providers.mdx b/apps/docs/guides/notification-providers.mdx new file mode 100644 index 0000000..1136d08 --- /dev/null +++ b/apps/docs/guides/notification-providers.mdx @@ -0,0 +1,247 @@ +--- +title: Notification Providers +description: "Set up real-time alerts through Discord, Slack, Telegram, Teams, or custom webhooks" +icon: bell +--- + +## Overview + +ByteSend supports multiple notification providers for real-time alerts about your account activity. Choose from Discord, Slack, Microsoft Teams, Telegram, or custom webhooks to receive notifications where you work. + +## Supported Providers + +- **Discord**: Direct messages and channel notifications +- **Slack**: Channel and direct message alerts +- **Microsoft Teams**: Team channel notifications +- **Telegram**: Direct Telegram messages +- **Webhook**: Custom JSON webhooks for programmatic handling + +## General Setup + +All notification providers follow a similar setup pattern: + +1. Log in to [ByteSend Dashboard](https://bytesend.cloud) +2. Navigate to **Settings** → **Notifications** +3. Find your desired provider under "Notification Channels" +4. Click **Connect** or **Configure** +5. Follow the provider-specific setup steps +6. Test the connection +7. Choose which alerts to receive + +## Alert Types + +Available notification triggers: + +- **Email Delivery Issues**: Emails failing to send or bounce +- **Domain Problems**: Domain verification failures or DNS issues +- **Team Changes**: Members added, removed, or roles changed +- **Billing Alerts**: Plan limit warnings, payment failures +- **Security Events**: Unusual activity, login attempts +- **API Quota**: Approaching rate limits or quota +- **Maintenance**: Scheduled maintenance notifications + +## Provider Setup Guides + +### Discord Notifications + +See [Discord Notifications](/guides/discord-notifications) for detailed setup instructions. + +**Quick Setup**: +1. Create a Discord webhook in your server +2. Go to **Settings** → **Notifications** → **Discord** +3. Paste your webhook URL +4. Choose alert types +5. Click **Test** to verify connection + +### Slack Notifications + +See [Slack Notifications](/guides/slack-notifications) for detailed setup instructions. + +**Quick Setup**: +1. Authorize ByteSend in Slack +2. Select the channel for alerts +3. Go to **Settings** → **Notifications** → **Slack** +4. Confirm the connection +5. Choose alert types + +### Microsoft Teams + +**Setup**: +1. In Teams, navigate to your desired channel +2. Click **⋯ More options** → **Connectors** → **Configure** +3. Search for "Webhook" and click **Configure** +4. Give your webhook a name +5. Copy the webhook URL +6. Go to **Settings** → **Notifications** → **Teams** +7. Paste the webhook URL +8. Select alert types + +**Testing**: +- Click **Send Test Message** to verify the connection +- You should see a test message in your Teams channel + +### Telegram + +**Prerequisites**: +- Telegram account (download from [telegram.org](https://telegram.org)) +- ByteSend Bot username + +**Setup**: +1. Open Telegram and search for "@ByteSendBot" +2. Click **Start** to initiate the bot +3. The bot will provide a unique code +4. Go to **Settings** → **Notifications** → **Telegram** +5. Enter the code provided by the bot +6. Click **Verify** +7. Select which alerts to receive + +**Receiving Alerts**: +- Notifications appear as direct messages from @ByteSendBot +- Choose between real-time or daily digest mode +- Reply to mute or configure alerts directly in Telegram + +### Custom Webhooks + +For advanced users who need programmatic handling of alerts. + +**Setup**: +1. Go to **Settings** → **Notifications** → **Custom Webhook** +2. Enter your webhook URL +3. (Optional) Add authentication headers or query parameters +4. Select alert types +5. Click **Test Webhook** to verify + +**Webhook Payload Format**: + +```json +{ + "event": "email_failed", + "timestamp": "2024-05-09T10:30:00Z", + "severity": "error", + "details": { + "email_id": "email_12345", + "recipient": "user@example.com", + "reason": "bounced", + "team_id": "team_789" + } +} +``` + +**Event Types**: +- `email_delivered`, `email_failed`, `email_bounced` +- `domain_verified`, `domain_verification_failed` +- `member_added`, `member_removed`, `role_changed` +- `plan_limit_warning`, `payment_failed` +- `security_alert`, `unusual_activity` +- `quota_warning`, `maintenance_notice` + +**Retry Logic**: +- Failed webhooks are automatically retried up to 5 times +- Retry backoff: 1s, 5s, 30s, 2min, 5min +- Webhook timeout: 30 seconds + +## Managing Notifications + +### Enable/Disable Providers + +1. Go to **Settings** → **Notifications** +2. Toggle providers on/off as needed +3. Disabled providers won't send notifications + +### Configure Alert Preferences + +For each provider: +1. Click **Configure** or the settings icon +2. Check/uncheck alert types you want to receive +3. Set delivery frequency (real-time, daily, weekly) +4. Click **Save** + +### Test Connection + +Before relying on a provider: +1. Click **Test** next to any connected provider +2. Should immediately receive a test notification +3. If no notification, check webhook URL or permissions + +### Remove Provider + +1. Go to **Settings** → **Notifications** +2. Click **Disconnect** next to the provider +3. Confirm removal +4. Notifications will no longer be sent to that provider + +## Notification Best Practices + +### Set Up Multiple Providers + +- Use Discord/Slack for immediate team alerts +- Use email for important billing notifications +- Use Telegram for critical issues +- Use webhooks for integration with your systems + +### Configure Alert Levels + +- **Critical** (billing, security): All channels +- **Important** (domain issues): Slack + email +- **Info** (stats, updates): Discord only + +### Alert Fatigue Prevention + +- Don't subscribe to every alert type +- Use digest mode for low-priority notifications +- Set specific channel for specific alert types +- Review and clean up unused providers + +### Testing in Development + +- Use separate webhooks/channels for development vs. production +- Clearly label test notifications +- Test provider connectivity before production deployment + +## Troubleshooting + +### Not Receiving Notifications + +**Discord**: +- Verify webhook URL is correct +- Check bot has channel permissions +- Try sending a test message + +**Slack**: +- Confirm ByteSend is authorized +- Check bot permissions in channel settings +- Verify channel isn't muted + +**Telegram**: +- Ensure you've replied "Start" to the bot +- Check that notifications aren't muted in Telegram +- Verify your code hasn't expired + +**Webhook**: +- Check endpoint is publicly accessible +- Verify SSL certificate is valid (for HTTPS) +- Review webhook logs for POST requests +- Confirm HTTP status code is 200-299 + +### Webhook Returning Errors + +- **400 Bad Request**: Check JSON payload format +- **401 Unauthorized**: Verify API key/auth headers +- **403 Forbidden**: Check permission scopes +- **500 Server Error**: Investigate endpoint logs +- **Timeout**: Check endpoint performance + +### Too Many Notifications + +1. Go to **Settings** → **Notifications** +2. Click **Configure** for the provider +3. Uncheck alert types you don't need +4. Switch to digest mode if available +5. Consider consolidating providers + +## Next Steps + +- [Set up Discord notifications](/guides/discord-notifications) +- [Set up Slack notifications](/guides/slack-notifications) +- [Manage your team members](/guides/plan-management) +- [Return to settings](/settings/notifications) diff --git a/apps/docs/guides/plan-management.mdx b/apps/docs/guides/plan-management.mdx new file mode 100644 index 0000000..4b5699b --- /dev/null +++ b/apps/docs/guides/plan-management.mdx @@ -0,0 +1,229 @@ +--- +title: Plan Management +description: "Manage your team, members, and account settings in ByteSend" +icon: users +--- + +## Overview + +The **Settings** panel in ByteSend allows you to manage your account, team members, and workspace preferences. Access settings by clicking your profile menu and selecting **Settings**. + +## Settings Tabs + +### General + +Manage your account basics and API keys. + +**Account Information**: +- Display name +- Email address +- Profile picture +- Account creation date + +**API Keys**: +- Generate new API keys for development and production +- View key creation date and last used timestamp +- Revoke old or unused keys + +### Members + +Manage team members and their access levels. + +#### Adding Team Members + +1. Navigate to **Settings** → **Members** +2. Click **Invite Member** +3. Enter the team member's email address +4. Select their role: + - **Admin**: Full access to all features and settings + - **Editor**: Can manage campaigns, domains, and templates + - **Viewer**: Read-only access to reports and analytics +5. Click **Send Invite** +6. The member will receive an email invitation and can accept it to join + +#### Member Roles + +| Role | Permissions | +|------|-------------| +| **Admin** | Full access, manage team members, billing, settings | +| **Editor** | Create/edit campaigns, manage templates, view analytics | +| **Viewer** | View reports, analytics, and read-only access | + +#### Removing Members + +1. Go to **Settings** → **Members** +2. Find the member to remove +3. Click **Remove Member** +4. Confirm the action +5. The member loses access immediately + +#### Changing Member Roles + +1. In **Settings** → **Members**, find the member +2. Click the role dropdown +3. Select the new role +4. Changes apply immediately + +### Usage + +Track your account usage and resource consumption. + +**Overview**: +- Current email volume used this month +- Verified domains count +- Team members count +- Webhooks count +- Storage usage + +**Resource Breakdown**: +- **Domains**: List of all verified domains with verification status +- **Webhooks**: Active webhooks with recent activity +- **Team Members**: Active team members and pending invitations + +**Upgrading**: +- See your current plan limits +- Link to upgrade to a higher plan if approaching limits + +### Notifications + +Configure alert preferences and notification methods. + +#### Alert Preferences + +Choose what events trigger notifications: +- Emails failing to send +- Domain verification issues +- Billing alerts +- Security events +- API quota warnings +- Team member additions/removals + +#### Notification Channels + +Choose how you receive alerts: + +**Email Notifications**: +- Receive alerts to your registered email +- Customizable digest frequency (real-time, daily, weekly) +- Unsubscribe from specific alert types + +**Discord Notifications**: +- Connect your Discord server +- Receive real-time alerts in a dedicated channel +- Requires Discord webhook setup + +**Slack Notifications**: +- Connect your Slack workspace +- Receive alerts in a designated Slack channel +- Requires Slack app authorization + +**Webhook Notifications**: +- Set up custom webhooks for all events +- Receive JSON payloads for programmatic handling +- Retry logic for failed deliveries + +**Telegram Notifications**: +- Connect your Telegram account +- Receive direct messages for critical alerts +- Optional alerts for all events + +#### Setting Up Notification Providers + +For detailed setup instructions: +- [Discord Notifications](/guides/discord-notifications) +- [Slack Notifications](/guides/slack-notifications) +- [Notification Providers Overview](/guides/notification-providers) + +## Team Management Best Practices + +### Organizing Your Team + +**Small Teams (1-5 members)**: +- Most team members can be Editors +- Have one Admin for account management +- Use Viewer role for observers/clients + +**Growing Teams (6-30 members)**: +- Designate 2-3 Admins for redundancy +- Use Editor role for active contributors +- Use Viewer role for stakeholders and reporting + +**Large Teams (30+ members)**: +- Multiple Admins by function (Billing Admin, Technical Admin) +- Use roles strategically based on responsibilities +- Use API keys for system integrations instead of personal accounts + +### Security Best Practices + +- **Remove inactive members promptly** to maintain security +- **Use strong passwords** and enable 2FA on your GitHub account (for GitHub OAuth users) +- **Rotate admin roles** to prevent over-privileging +- **Review team members regularly** in your monthly management checklist +- **Use different API keys** for different integrations +- **Never share API keys** between team members — generate individual keys + +### Offboarding Team Members + +When a team member leaves: + +1. Remove their account from **Settings** → **Members** +2. Revoke any API keys they created +3. Transfer ownership of critical campaigns/templates +4. Update GitHub OAuth settings if applicable +5. Document which features they managed + +## Account Security + +### Password & Authentication + +If using email/password authentication: +- Change your password regularly (every 90 days recommended) +- Use a strong, unique password +- Never share your password with team members + +If using GitHub OAuth: +- [Enable 2FA on your GitHub account](https://github.com/settings/security) +- [Review connected applications](https://github.com/settings/apps/authorizations) +- Revoke ByteSend access if switching providers + +### Session Management + +- Active sessions are displayed in your security settings +- Sign out from all devices if suspicious activity is detected +- Sessions automatically expire after 30 days of inactivity + +## Troubleshooting + +### Can't Add Team Members + +- Verify the email address is correct +- Check that the invite hasn't already been sent +- Ensure your plan allows the number of team members (free plan = 1 member) + +### Member Didn't Receive Invitation + +- Check their spam/junk folder +- Ask them to sign up directly at [ByteSend](https://bytesend.cloud) +- Resend the invitation from the settings panel + +### Need to Change Someone's Role + +1. Go to **Settings** → **Members** +2. Click the role dropdown for that member +3. Select the new role +4. Changes take effect immediately + +### Forgotten Password + +1. Click **Forgot Password** on the login page +2. Enter your email address +3. Check your email for the reset link +4. Click the link and set a new password +5. Log in with your new password + +## Next Steps + +- [View your usage](/settings/usage) +- [Set up notifications](/settings/notifications) +- [Upgrade your plan](/guides/plans-and-pricing) +- [Configure notification providers](/guides/notification-providers) diff --git a/apps/docs/guides/plans-and-pricing.mdx b/apps/docs/guides/plans-and-pricing.mdx new file mode 100644 index 0000000..8e784ab --- /dev/null +++ b/apps/docs/guides/plans-and-pricing.mdx @@ -0,0 +1,206 @@ +--- +title: Plans & Pricing +description: "Choose the right ByteSend plan for your email needs" +icon: credit-card +--- + +## Overview + +ByteSend offers flexible pricing plans to accommodate teams of any size, from solopreneurs to enterprises. Choose the plan that best fits your email volume and team requirements. + +## Available Plans + +### Free Plan + +Perfect for getting started with ByteSend. + +**Monthly Cost**: Free + +**Limits**: +- 100 emails/month +- 1 domain +- 1 team member +- 1 webhook +- 7-day message history + +**Features**: +- Full API access +- Email templates +- Basic analytics +- SMTP support +- Community support + +**Best for**: Personal projects, testing, and development + +### BASIC Plan + +For growing teams sending regular emails. + +**Monthly Cost**: CA$20/month (billed annually: CA$200/year) + +**Limits**: +- 100,000 emails/month +- 12 verified domains +- 30 team members +- Unlimited webhooks +- 90-day message history + +**Features**: +- Everything in Free plan +- Advanced analytics +- Priority email support +- Custom templates +- Webhook retry logic +- Email scheduling +- SMTP enhanced features + +**Best for**: Small businesses, startups, and growing teams + +### LIFETIME Plan + +One-time payment for unlimited access. Ideal for long-term projects. + +**One-Time Cost**: CA$199 (paid once, forever) + +**Limits**: +- 500,000 emails/month +- 30 verified domains +- 100 team members +- Unlimited webhooks +- Unlimited message history + +**Features**: +- Everything in BASIC plan +- Advanced features and future updates +- Priority support +- No recurring billing + +**Best for**: Agencies, established businesses, and cost-conscious teams + +## Plan Comparison + +| Feature | Free | BASIC | LIFETIME | +|---------|------|-------|----------| +| **Email Volume** | 100/mo | 100,000/mo | 500,000/mo | +| **Domains** | 1 | 12 | 30 | +| **Team Members** | 1 | 30 | 100 | +| **Message History** | 7 days | 90 days | Unlimited | +| **API Access** | ✓ | ✓ | ✓ | +| **Analytics** | Basic | Advanced | Advanced | +| **SMTP Support** | ✓ | ✓ | ✓ | +| **Email Templates** | ✓ | ✓ | ✓ | +| **Webhooks** | 1 | Unlimited | Unlimited | +| **Support** | Community | Priority | Priority | +| **Cost** | Free | CA$20/mo | CA$199 (one-time) | + +## Upgrading Your Plan + +### From Free to BASIC + +1. Log in to your [ByteSend Dashboard](https://bytesend.cloud) +2. Navigate to **Settings** → **Billing** → **Plans** +3. Click **Upgrade to BASIC** +4. Enter your payment details +5. Confirm the upgrade +6. Your plan is active immediately + +### From Free/BASIC to LIFETIME + +1. Go to **Settings** → **Billing** → **Plans** +2. Click **Upgrade to LIFETIME** +3. Review the one-time cost +4. Enter your payment details +5. Complete the purchase +6. Lifetime access is activated immediately + +### Prorated Pricing + +If you upgrade mid-month: +- If on an annual BASIC plan: You'll receive a credit for your remaining months +- If on a monthly BASIC plan: The upgrade to LIFETIME is a flat one-time fee +- Free plan upgrades are charged the full plan amount + +## Downgrading Your Plan + +### From BASIC to Free + +1. Go to **Settings** → **Billing** +2. Click **Downgrade to Free** +3. Confirm the action +4. Your plan downgrades at the end of your current billing cycle +5. You'll lose access to BASIC features when downgraded + + +Downgrading may affect your account if you exceed free tier limits. For example: +- Excess team members will be archived +- Excess domains will be temporarily disabled +- Webhooks beyond the limit will be disabled + + +## Frequently Asked Questions + +### What happens if I exceed my email limit? + +- Emails exceeding your monthly limit will be queued +- You can send them immediately by upgrading your plan +- You'll receive a notification when approaching your limit + +### Can I change my plan after purchase? + +Yes, you can upgrade or downgrade at any time from **Settings** → **Billing** → **Plans**. + +### Do you offer annual billing discounts? + +Yes! BASIC plan annual billing saves you 2 months: +- Monthly: CA$20 × 12 = CA$240/year +- Annual: CA$200/year (saves CA$40) + +### Is the LIFETIME plan really permanent? + +Yes! With the LIFETIME plan: +- No recurring charges after the initial purchase +- You keep your plan even if you stop using ByteSend +- Future features and updates are included + +### Do you offer enterprise plans? + +Yes! For high-volume needs (1M+ emails/month), we offer custom enterprise pricing. [Contact sales](https://discord.gg/xqkqzVRC4S) to discuss your requirements. + +### Can I cancel my subscription? + +You can cancel your BASIC plan at any time. Simply go to **Settings** → **Billing** and click **Cancel Plan**. You'll retain access until the end of your billing period. + +## Billing & Payments + +### Accepted Payment Methods + +- Credit/Debit cards (Visa, Mastercard, American Express) +- PayPal +- Wire transfer (for enterprise customers) + +### Invoices + +All invoices are available in your dashboard: + +1. Go to **Settings** → **Billing** → **Invoices** +2. View, download, or email invoices +3. Invoices are emailed automatically after each billing cycle + +### Tax Information + +- VAT/GST is calculated based on your billing location +- Tax information can be added in **Settings** → **Billing** → **Tax** +- All prices displayed are in CAD + +## Support + +For billing questions or concerns: + +- **Free Plan**: Community support via [Discord](https://discord.gg/xqkqzVRC4S) +- **BASIC/LIFETIME Plans**: Priority email and Discord support + +## Next Steps + +- [Upgrade your plan](https://bytesend.cloud/settings/billing) +- [Manage your team members](/guides/plan-management) +- [Explore billing operations](/guides/admin-operations) diff --git a/apps/docs/guides/slack-notifications.mdx b/apps/docs/guides/slack-notifications.mdx new file mode 100644 index 0000000..784b0d6 --- /dev/null +++ b/apps/docs/guides/slack-notifications.mdx @@ -0,0 +1,285 @@ +--- +title: Slack Notifications +description: "Integrate ByteSend alerts with your Slack workspace" +icon: slack +--- + +## Overview + +Connect ByteSend to your Slack workspace to receive real-time notifications about email delivery, team activity, billing updates, and more directly in your Slack channels. + +## Prerequisites + +- Slack workspace (free or paid plan) +- Admin or Editor role in ByteSend +- Slack workspace admin or app installation permissions + +## Setting Up Slack Integration + +### Step 1: Authorize ByteSend in Slack + +1. Log in to [ByteSend Dashboard](https://bytesend.cloud) +2. Navigate to **Settings** → **Notifications** +3. Find **Slack** under "Notification Channels" +4. Click **Connect** or **Add Slack** +5. Click **Authorize with Slack** + +You'll be redirected to Slack's authorization page. + +### Step 2: Grant Permissions + +On the Slack authorization page: + +1. Select your workspace from the dropdown (if you have multiple) +2. Review the permissions ByteSend requests +3. Click **Allow** to authorize + +**Permissions requested**: +- Post messages to channels +- Send direct messages +- Access user profiles +- Read workspace information + +### Step 3: Choose Notification Channel + +After authorization: + +1. Select which Slack channel receives notifications (e.g., #bytesend-alerts) +2. Or choose to send direct messages to your Slack user +3. Click **Save** + +### Test the Connection + +1. ByteSend will ask to send a test message +2. Click **Send Test** +3. Check your Slack channel or DMs for the test notification +4. If successful, you're ready to receive alerts + +## Configuring Slack Alerts + +### Alert Types + +Choose which events trigger Slack notifications: + +- **Email Events**: Delivery, bounces, opens, clicks, failures +- **Domain Management**: Verification status, DNS issues +- **Team Changes**: Members added/removed, role changes +- **Billing**: Limit warnings, payment failures, upgrades +- **Security**: Suspicious activity, unusual login patterns +- **API**: Rate limit warnings, quota updates +- **Maintenance**: Scheduled downtime, updates + +### Notification Frequency + +- **Real-time**: Immediate notification as events occur +- **Daily Digest**: Single message at end of day summarizing events +- **Weekly Digest**: Single message summarizing the week's events +- **Critical Only**: Only severe issues and errors + +**Recommendation**: Use real-time for critical alerts, digest for informational updates. + +### Message Formatting + +Slack messages include: + +**Email Delivery Alert**: +``` +⚡ Email Bounced +Team: Your Team +Recipient: user@example.com +Bounce Type: Permanent +Time: May 9, 10:30 AM +``` + +**Team Member Alert**: +``` +👥 New Team Member +Name: John Doe +Email: john@example.com +Role: Editor +Added by: Admin +``` + +All messages include a **View in Dashboard** link for quick access. + +## Managing Your Slack Connection + +### Update Alert Channel + +To change which channel receives alerts: + +1. Go to **Settings** → **Notifications** → **Slack** +2. Click **Change Channel** +3. Select a different channel +4. Click **Save** + +### Pause Notifications + +To temporarily stop receiving Slack alerts: + +1. Go to **Settings** → **Notifications** → **Slack** +2. Click **Pause** +3. Notifications will stop +4. Click **Resume** to re-enable + +### Disconnect Slack + +To remove the Slack integration: + +1. Go to **Settings** → **Notifications** +2. Click **Disconnect** next to Slack +3. Confirm the action +4. ByteSend will no longer send Slack messages + +### Revoke in Slack + +To remove ByteSend from your Slack workspace: + +1. In Slack, click your workspace name (top left) +2. Select **Settings & administration** → **Manage apps** +3. Search for "ByteSend" +4. Click **ByteSend** +5. Click **Remove App** +6. Confirm removal + +## Advanced Slack Configuration + +### Multiple Channels + +To send different alerts to different channels, you can: + +1. Disconnect the current Slack integration +2. Reconnect and choose a different channel +3. Or use a Slack workflow to route messages + +### Filtering for Your Team + +Configure which team members receive notifications: + +1. Go to **Settings** → **Notifications** → **Slack** +2. Under "Notification Recipients", select team members +3. Only selected members will be @mentioned in alerts +4. Others can still see the message + +### Slack Workflow Integration + +Create Slack workflows triggered by ByteSend alerts: + +1. In your Slack channel, click the menu (⋯) +2. Select **Automations** +3. Create a workflow triggered by messages containing "ByteSend" +4. Set up actions (create tasks, send emails, etc.) + +**Example Workflow**: +- Trigger: Email delivery fails +- Action: Create task in project management tool +- Action: Notify #support channel + +### Message Threading + +Organize alerts by type: + +1. Reply to ByteSend messages to start threads +2. Related alerts are grouped together +3. Easy to track related issues +4. Less channel clutter + +## Troubleshooting + +### Not Receiving Slack Notifications + +**Authorization issue**: +- Disconnect and re-authorize ByteSend in Slack +- Check that you have permissions to install apps +- Try a different Slack workspace + +**Channel issue**: +- Verify the bot can access the selected channel +- Check channel permissions +- Ensure the channel isn't archived +- Try selecting a different channel + +**Settings issue**: +- Verify alert types are enabled +- Check notification frequency isn't set to "never" +- Try sending a test message + +### Not a Member of Channel + +If you see "ByteSend cannot post to this channel": + +1. Manually join the channel in Slack +2. Go back to ByteSend settings +3. Reconnect/refresh Slack integration +4. Try again + +### Connection Keeps Failing + +1. Disconnect Slack from ByteSend +2. Revoke ByteSend in Slack app settings +3. Clear your browser cache +4. Reconnect from scratch +5. Contact support if still failing + +### Too Many Notifications + +To reduce alert fatigue: + +1. Uncheck alert types you don't need +2. Switch to digest mode +3. Create a separate Slack workspace or channel for low-priority alerts +4. Mute the channel during off-hours + +### Messages Not Formatting Correctly + +- Refresh your Slack window +- Try disconnecting and reconnecting ByteSend +- Update your Slack app to the latest version +- Contact support if formatting still broken + +## Best Practices + +### Channel Organization + +- Create dedicated channels: + - `#bytesend-critical` for errors and urgent alerts + - `#bytesend-daily` for daily digests + - `#bytesend-team` for team and billing updates + +- Use channel descriptions: "Real-time ByteSend notifications" +- Pin alert configuration docs + +### Alert Configuration + +- **Critical alerts** (email failures, payment issues): Real-time +- **Important alerts** (domain issues, member changes): Daily digest +- **Informational** (stats, updates): Weekly digest or custom channel + +### Team Communication + +- Establish response protocols for critical alerts +- @mention relevant team members in threads +- Document common alert meanings +- Share alert guidelines with team + +### Privacy & Security + +- Don't share Slack channel links that contain sensitive info +- Review who has access to notification channels +- Rotate channel access as team changes +- Archive old notifications periodically + +### Monitoring + +- Periodically review which alerts your team actually uses +- Adjust settings monthly based on usage patterns +- Evaluate if some alerts can be disabled +- Consider consolidating channels + +## Next Steps + +- [Return to notification providers](/guides/notification-providers) +- [Set up Discord notifications](/guides/discord-notifications) +- [Manage all notifications](/settings/notifications) +- [Configure team members](/guides/plan-management) +- [Explore billing operations](/guides/admin-operations) diff --git a/apps/docs/images/aws/key-1.png b/apps/docs/images/aws/key-1.png deleted file mode 100644 index 269fde8..0000000 Binary files a/apps/docs/images/aws/key-1.png and /dev/null differ diff --git a/apps/docs/images/aws/key-2.png b/apps/docs/images/aws/key-2.png deleted file mode 100644 index b11d831..0000000 Binary files a/apps/docs/images/aws/key-2.png and /dev/null differ diff --git a/apps/docs/images/aws/key-3.png b/apps/docs/images/aws/key-3.png deleted file mode 100644 index 08915e8..0000000 Binary files a/apps/docs/images/aws/key-3.png and /dev/null differ diff --git a/apps/docs/images/aws/key-4.png b/apps/docs/images/aws/key-4.png deleted file mode 100644 index f573c13..0000000 Binary files a/apps/docs/images/aws/key-4.png and /dev/null differ diff --git a/apps/docs/images/aws/key-5.png b/apps/docs/images/aws/key-5.png deleted file mode 100644 index 5c9b04b..0000000 Binary files a/apps/docs/images/aws/key-5.png and /dev/null differ diff --git a/apps/docs/images/aws/key-6.png b/apps/docs/images/aws/key-6.png deleted file mode 100644 index 99d6471..0000000 Binary files a/apps/docs/images/aws/key-6.png and /dev/null differ diff --git a/apps/docs/images/changelog/schedule-campaign.png b/apps/docs/images/changelog/schedule-campaign.png deleted file mode 100644 index c5f5ac1..0000000 Binary files a/apps/docs/images/changelog/schedule-campaign.png and /dev/null differ diff --git a/apps/docs/images/changelog/webhook.png b/apps/docs/images/changelog/webhook.png deleted file mode 100644 index ea7a85e..0000000 Binary files a/apps/docs/images/changelog/webhook.png and /dev/null differ diff --git a/apps/docs/images/github-callback.png b/apps/docs/images/github-callback.png deleted file mode 100644 index 0a32281..0000000 Binary files a/apps/docs/images/github-callback.png and /dev/null differ diff --git a/apps/docs/images/ses-settings/add-ses-settings.png b/apps/docs/images/ses-settings/add-ses-settings.png deleted file mode 100644 index 7d766cc..0000000 Binary files a/apps/docs/images/ses-settings/add-ses-settings.png and /dev/null differ diff --git a/apps/docs/images/ses-settings/sandbox.png b/apps/docs/images/ses-settings/sandbox.png deleted file mode 100644 index 1c105d0..0000000 Binary files a/apps/docs/images/ses-settings/sandbox.png and /dev/null differ diff --git a/apps/docs/introduction.mdx b/apps/docs/introduction.mdx index 7612138..fd2d82c 100644 --- a/apps/docs/introduction.mdx +++ b/apps/docs/introduction.mdx @@ -1,41 +1,234 @@ ---- title: Introduction description: "ByteSend is a developer-friendly alternative to Resend, Sendgrid, Mailgun, and Postmark." icon: rocket ---- -## Setting up -Quicklinks to set up your account and get started +## Welcome to ByteSend + +ByteSend is a powerful, open-source email delivery platform designed for developers. Send transactional and marketing emails reliably with a simple REST API, SMTP support, and comprehensive analytics. + +## What's New in v0.2.5 + +**Smarter Billing, Better Alerts** + +- **GitHub OAuth**: Secure single sign-on with your GitHub account +- **Notification Providers**: Real-time alerts via Discord, Slack, Microsoft Teams, Telegram, and webhooks +- **Enhanced Admin Controls**: Better team and billing management +- **Flexible Pricing**: BASIC and LIFETIME plans with adjusted limits +- **Restructured Settings**: Cleaner, more intuitive account management + +## Getting Started - Add domains to send emails + Add domains to send emails. We'll guide you through verification. - Generate API key to send emails from your app. + Generate an API key to start sending emails from your app. + + + + Send a test email using the REST API or SDK. + + + + Prefer SMTP? Connect via our SMTP server. + + + +## Authentication & Security + + + + Sign in securely with your GitHub account. + + + + Learn how to authenticate API requests with your API key. + + +## Account & Billing + + + + Choose the plan that fits your needs (Free, BASIC, or LIFETIME). + + + + Manage team members, settings, and account preferences. + + + Advanced billing and team administration features. + + + +## Notifications & Alerts + +Set up real-time notifications for your team across multiple platforms: + + + + Overview of all notification options. + + + + Receive alerts in your Discord server. + + + + Send alerts to your Slack workspace. + + + +## Integration Guides + + + + Receive real-time notifications about email events. + + + + Build beautiful emails with React Email and ByteSend. + + + + Implement compliant double opt-in flows. + + + + Create personalized email campaigns at scale. + + + +## API Reference + + + - Learn how to use our API to send emails programmatically. + Explore the complete ByteSend REST API with interactive examples. + + + +## Self-Hosting + +Want to run ByteSend on your own infrastructure? + + + + Complete guide to self-host ByteSend with Docker or bare-metal. - + Set up the ByteSend SMTP server. + + + - Send emails with SMTP server instead of REST API. + Security considerations for self-hosted deployments. + +## Key Features + +- **Easy Integration**: Simple REST API, JavaScript/Python SDKs, and SMTP support +- **Real-time Analytics**: Track delivery, opens, clicks, bounces, and more +- **Team Collaboration**: Add team members with role-based access control +- **Flexible Billing**: Pay-as-you-go or lifetime access +- **Developer Friendly**: Full API documentation, code examples, and webhooks +- **Open Source**: Self-host or use our managed cloud platform +- **Notifications**: Discord, Slack, Teams, Telegram, and custom webhooks + +## Quick Links + +- [View GitHub Repository](https://github.com/NodeByteLTD/ByteSend) +- [Join Community Discord](https://discord.gg/xqkqzVRC4S) +- [Follow on Twitter](https://twitter.com/TryByteSend) +- [Dashboard](https://bytesend.cloud) + +## Need Help? + +- Browse the [API Reference](/api-reference/introduction) +- Check out [Integration Guides](/guides/webhooks) +- Join our [Community Discord](https://discord.gg/xqkqzVRC4S) +- View [GitHub Discussions](https://github.com/NodeByteLTD/ByteSend/discussions) diff --git a/apps/docs/updates/product-update-1.mdx b/apps/docs/updates/product-update-1.mdx deleted file mode 100644 index 3189e52..0000000 --- a/apps/docs/updates/product-update-1.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "Product Update: 1" -description: "Campaign Scheduling and API, Custom email headers" ---- - - - v1.7.0 Product Update - - - -### Campaign Scheduling with Natural Language - -Schedule your campaigns effortlessly using natural language inputs like "tomorrow at 9am" or "next Monday at 10am". Available via API as well - -### Campaigns API - -We're doubling down on APIs. You can now create, schedule, and manage campaign emails programmatically through our API. - -Check out the [Campaign API documentation](/api-reference/campaigns/create-campaign) to get started. - -### Custom email headers -You can now send custom email headers via api, comes in handy when you want to send unsub links for transactional emails - -Checkout the [docs here](/api-reference/emails/send-email#body-headers) - -### Other Improvements - -- Upload large amounts of contacts without experiencing UI slowness -- Delete Domain API -- Export emails with bounce reason and filters -- Create API keys domain restriction diff --git a/packages/python-sdk/pyproject.toml b/packages/python-sdk/pyproject.toml index 277862f..f5483c0 100644 --- a/packages/python-sdk/pyproject.toml +++ b/packages/python-sdk/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "bytesend" -version = "0.2.10" +version = "0.1.0" description = "Python SDK for the ByteSend API" authors = ["NodeByte LTD"] license = "MIT"