Skip to content

docs(source-brevo): rewrite setup guide and document rate limits - #76849

Merged
devin-ai-integration[bot] merged 1 commit into
masterfrom
devin/1776783539-docs-source-brevo
Apr 25, 2026
Merged

devin-ai-integration[bot] merged 1 commit into
masterfrom
devin/1776783539-docs-source-brevo

Conversation

@devin-ai-integration

@devin-ai-integration devin-ai-integration Bot commented Apr 21, 2026 •

Copy link
Copy Markdown
Contributor

Documentation Confidence Assessment

Overall Confidence: 4/5

Dimension Score Rationale
Code Comprehension 5/5 Manifest-only YAML; streams, auth, pagination, and error handling are all declarative.
API Documentation Quality 5/5 Brevo publishes comprehensive official docs (API reference, auth guide, rate-limit tables, status page) — all four are listed in externalDocumentationUrls.
Change Scope & Risk 3/5 Moderate rewrite of the setup/auth sections plus a new rate-limit section and one changelog-date correction; 79 insertions / 41 deletions.
Existing Doc Maturity 2/5 Prior doc was a 95-line boilerplate with a one-line auth section and no performance guidance.
Connector Sensitivity 5/5 Community connector, ql=100, sl=100, releaseStage: alpha.
Triggering Context 5/5 Triggered from a small merged PR (SDM base-image bump, #76844).

What I Verified vs. What I Inferred

  • Verified from code (airbyte-integrations/connectors/source-brevo/manifest.yaml):
    • url_base: https://api.brevo.com/v3/ and ApiKeyAuthenticator injecting api-key into the request header.
    • Spec: api_key and start_date are the only configuration fields; start_date uses the regex ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$.
    • check.stream_names: [contacts] — the connection check calls the contacts endpoint.
    • Complete list of streams, their primary keys, and which have incremental_sync blocks.
    • Incremental streams pass the cursor value via the modifiedSince request parameter.
    • 429 responses are handled with ExponentialBackoffStrategy.
  • Verified from API docs (https://developers.brevo.com/docs/api-limits, https://help.brevo.com/hc/en-us/articles/209467485, https://developers.sendinblue.com/docs/api-key-authentication):
    • Brevo general-tier rate limits: /v3/contacts/… allows 10 RPS; "all other endpoints" fall back to 100 RPH.
    • API keys are created on the API Keys & MCP page and displayed once.
    • Generating keys requires the "API keys" user permission.
  • Verified from git history:
  • Inferred (reasonable but not independently confirmed):
    • The "Full Refresh | Append + Deduped" sync mode availability matrix for each stream (I listed standard Airbyte support for streams with primary keys; not all streams were individually verified in the connector's acceptance tests).
    • The characterization "most other endpoints this connector uses" as falling under Brevo's "all other endpoints" 100 RPH bucket (based on inspecting the manifest's URL paths against Brevo's published per-endpoint table).

Areas of Concern

  • Brevo's "all other endpoints: 100 RPH" is strikingly low; a reviewer familiar with Brevo may want to confirm this applies to CRM/campaigns endpoints rather than a more generous undocumented bucket.
  • I did not run the connector, so sync-mode combinations in the "Supported sync modes" section are stated from Airbyte's general semantics rather than observed behavior.

What

Rewrites the Brevo source connector documentation so a data engineer new to Brevo can set up the connector end-to-end from the page, and documents behavior the previous page omitted.

Triggered by review of commit 5bcef3e (#76844), which bumped the SDM base image. The bump itself introduced no user-facing behavior change, but review of the page surfaced gaps worth addressing.

How

Corrections

Additions

  • New Prerequisites list (Brevo account, user with API keys permission, API key).
  • New Generate an API key step-by-step section based on Brevo's official help article.
  • New Set up the Brevo source in Airbyte section that documents the YYYY-MM-DDTHH:MM:SSZ UTC format required by start_date (from the manifest regex) and notes that the connection check hits the contacts endpoint.
  • New Supported sync modes section.
  • New Performance considerations section citing Brevo's rate limits documentation, specifically that /v3/contacts/… has a higher limit (10 RPS) than the 100 RPH catch-all that applies to the other endpoints this connector uses.

Restructuring

  • Renamed Configuration table to Configuration reference and dropped the unused "Default Value" column (neither field has a default).
  • Kept the full streams table; no streams were added, removed, or renamed.

Review guide

  1. docs/integrations/sources/brevo.md — the whole file, especially:
    • Lines 7–22 (prerequisites, API key generation).
    • Lines 77–81 (rate-limit claims — see "Areas of Concern" above).
    • Line 89 (corrected 0.2.30 date).

User Impact

New Brevo users get a self-contained setup guide; existing users see accurate rate-limit guidance and a corrected changelog date. No functional connector change.

Can this PR be safely reverted and rolled back?

  • YES 💚
  • NO ❌

Note: I am an AI assistant (Devin) and have proposed these documentation updates based on a review of the connector source code and Brevo's official developer docs. Reviewers may merge, modify, or close this PR as they see fit.

Link to Devin session: https://app.devin.ai/sessions/e6c9f311b5394a67b96081edd0b5ab43

- Add prerequisites (Brevo account, API keys permission).
- Rewrite API key generation steps based on Brevo's help docs.
- Document start_date UTC format requirement.
- Add rate limit guidance linking to Brevo's rate limit tiers.
- Use Markdown links instead of backtick URLs.
- Correct changelog date for 0.2.30 to 2026-04-01 (PR #75946 merge date).

Co-Authored-By: bot_apk <apk@cognition.ai>
@devin-ai-integration

Copy link
Copy Markdown
Contributor Author

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@github-actions

Copy link
Copy Markdown
Contributor

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

  • 🛠️ Quick Fixes
    • /format-fix - Fixes most formatting issues.
    • /bump-version - Bumps connector versions, scraping changelog description from the PR title.
      • Bump types: patch (default), minor, major, major_rc, rc, promote.
      • The rc type is a smart default: applies minor_rc if stable, or bumps the RC number if already RC.
      • The promote type strips the RC suffix to finalize a release.
      • Example: /bump-version type=rc or /bump-version type=minor
    • /bump-progressive-rollout-version - Alias for /bump-version type=rc. Bumps with an RC suffix and enables progressive rollout.
  • ❇️ AI Testing and Review (internal link: AI-SDLC Docs):
    • /ai-prove-fix - Runs prerelease readiness checks, including testing against customer connections.
    • /ai-canary-prerelease - Rolls out prerelease to 5-10 connections for canary testing.
    • /ai-review - AI-powered PR review for connector safety and quality gates.
  • 🚀 Connector Releases:
    • /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-preview.{git-sha}) for all modified connectors in the PR.
  • ☕️ JVM connectors:
    • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
      Example: /update-connector-cdk-version connector=destination-bigquery
  • 🐍 Python connectors:
    • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
    • /poe source example lock - Alias for /poe connector source-example lock.
    • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
    • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.
  • ⚙️ Admin commands:
    • /force-merge reason="<REASON>" - Force merges the PR using admin privileges, bypassing CI checks. Requires a reason.
      Example: /force-merge reason="CI is flaky, tests pass locally"
📚 Show Repo Guidance

Helpful Resources

📝 Edit this welcome message.

@github-actions

Copy link
Copy Markdown
Contributor

Deploy preview for airbyte-docs ready!

Project:airbyte-docs
Status: ✅  Deploy successful!
Preview URL:https://airbyte-docs-ot4u46rsf-airbyte-growth.vercel.app
Latest Commit:6b5a121

Deployed with vercel-action

@airbyte-support-bot

Copy link
Copy Markdown
Contributor

↪️ Triggering /ai-review per Hands-Free AI Triage Project triage next step.

Reason: Docs/chore PR; no runtime behavior change requires prove-fix. Triggering review for PR hygiene and content validation.

Devin session

@octavia-bot
octavia-bot Bot marked this pull request as ready for review April 22, 2026 11:55
@octavia-bot

octavia-bot Bot commented Apr 22, 2026 •

Copy link
Copy Markdown
Contributor

AI PR Review starting...

Reviewing PR for connector safety and quality.
View playbook

✅ Devin AI session created successfully!

@devin-ai-integration

devin-ai-integration Bot commented Apr 22, 2026 •

Copy link
Copy Markdown
Contributor Author

AI PR Review Report

Review Action: APPROVED
Risk Level: 0 — Documentation-only change to docs/integrations/sources/brevo.md; no runtime code, metadata, or dependency changes.

Gate Status
PR Hygiene PASS
Code Hygiene PASS
Test Coverage PASS
Code Security PASS
Per-Record Performance PASS
Breaking Dependencies PASS
Backwards Compatibility PASS
Forwards Compatibility PASS
Behavioral Changes PASS
Out-of-Scope Changes PASS
CI Checks PASS
Live / E2E Tests PASS

📋 PR Details

Connector & PR Info

Connector(s): source-brevo (documentation only)
PR: #76849
HEAD SHA: 6b5a121df2aef74b87d14a5fddf5d238afff9b7
Session: https://app.devin.ai/sessions/44281457117b497db5dcb0b680a60ea6

Risk Level

Level: 0 — No production impact
Rationale: Pure Markdown change to docs/integrations/sources/brevo.md. No connector source code, manifest.yaml, metadata.yaml, spec.json, dependency files, or CI workflows were modified. Worst case is a docs-side readability issue.

Review Action Details

APPROVED — All enforced gates pass. octavia-bot will submit an APPROVE review on behalf of this report. APPROVE means "no blocking objection"; it does not authorize auto-merge. The merge decision remains with human reviewers or a separate auto-merge policy that consumes decision and risk_level from the metrics marker.

🔍 Gate Evaluation Details

Gate-by-Gate Analysis

Gate Status Enforced? Details
PR Hygiene PASS Yes PR body length is 5859 chars (well above 50-char threshold) and contains a detailed "What / How / Verified" description. No unresolved human reviewer comments. Changelog requirement does not apply — no connector source files were modified.
Code Hygiene PASS WARNING No connector source code modified, so test-coverage heuristic does not trigger. Docs-only changes are exempt.
Test Coverage PASS Yes Docs-only change (docs/**) is exempt per the gate's exemption list. No behavioral change requiring tests.
Code Security PASS Yes No files match security-sensitive path patterns (no auth/credential/encryption modules, no manifest/metadata changes). No security keywords in the diff hunks.
Per-Record Performance PASS WARNING No Python/Kotlin/Java source touched; no record-processing code paths modified.
Breaking Dependencies PASS WARNING No build.gradle*, pyproject.toml, poetry.lock, or requirements.txt changes.
Backwards Compatibility PASS Warning (elevates Risk Level) No spec/metadata/schema changes. Docs-only content addition.
Forwards Compatibility PASS Warning (elevates Risk Level) No state/cursor/pagination/transformation logic changed; no keywords in diff hunks.
Behavioral Changes PASS Warning (elevates Risk Level) No rate-limit/retry/timeout/error-handler code changes. Rate-limit values mentioned in the docs are sourced from Brevo's public documentation and do not change connector behavior.
Out-of-Scope Changes PASS Skip Change is entirely under docs/** (in-scope).
CI Checks PASS Yes 46 checks completed successfully, 0 failed. Docs-specific checks (Docs / Vale, Docs / MarkDownLint, Build Airbyte Docs, Vercel – airbyte-docs) all passed. No connectors modified, so connector Lint/Test jobs are no-ops (green).
Live / E2E Tests PASS Yes Docs-only change — validation not required per the gate's "not required" patterns (docs/**, *.md).
📚 Evidence Consulted

Evidence

  • Changed files (1): docs/integrations/sources/brevo.md (+79 / −41, modified)
  • CI checks: 46 passed, 0 failed, 0 pending, 16 skipped at HEAD SHA 6b5a121d. Key docs checks: Docs / Vale ✅, Docs / MarkDownLint ✅, Build Airbyte Docs ✅, Vercel – airbyte-docs ✅.
  • PR labels: area/documentation, team/documentation, auto-merge
  • PR description: Present (5859 chars) — includes confidence assessment, verified vs inferred claims, and a detailed What / How summary.
  • Existing bot reviews: None at this HEAD SHA.
  • Author: devin-ai-integration[bot]
  • Connector scope: source-brevo is a community connector (releaseStage: alpha, ql=100, sl=100); documentation improvements carry no runtime risk.

Devin session

@octavia-bot-admin octavia-bot-admin Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-approved by auto-merge workflow.

@octavia-bot-admin octavia-bot-admin Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-approved by auto-merge workflow.

@octavia-bot-admin octavia-bot-admin Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-approved by auto-merge workflow.

@octavia-bot-admin octavia-bot-admin Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-approved by auto-merge workflow.

@octavia-bot-admin octavia-bot-admin Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-approved by auto-merge workflow.

@octavia-bot-admin octavia-bot-admin Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-approved by auto-merge workflow.

@octavia-bot-admin octavia-bot-admin Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-approved by auto-merge workflow.

@octavia-bot-admin octavia-bot-admin Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-approved by auto-merge workflow.

@octavia-bot-admin octavia-bot-admin Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-approved by auto-merge workflow.

@octavia-bot-admin octavia-bot-admin Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-approved by auto-merge workflow.

@octavia-bot-admin octavia-bot-admin Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-approved by auto-merge workflow.

@devin-ai-integration
devin-ai-integration Bot merged commit 8479488 into master Apr 25, 2026
63 checks passed
@devin-ai-integration
devin-ai-integration Bot deleted the devin/1776783539-docs-source-brevo branch April 25, 2026 20:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/documentation Improvements or additions to documentation auto-merge team/documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant