Sendblue Python Integration (Async)

Async, typed integration for the Sendblue API with robust retries, error handling, and client-side pacing. Mirrors the structure used in the Lob integration for consistency.

Features

• 100% async via aiohttp
• Typed responses with Pydantic v2 models
• Exponential backoff retries (backoff) with jitter
• Sendblue auth headers (sb-api-key-id, sb-api-secret-key)
• Client-side pacing to complement server rate limits
• Clear exceptions: auth, rate limit, validation, not found, server, timeout

Environment

Set the following (e.g., in .env):

• SENDBLUE_API_KEY_ID (required)
• SENDBLUE_API_SECRET_KEY (required)
• SENDBLUE_BASE_URL (default: https://api.sendblue.co/api)
• SENDBLUE_TIMEOUT (default: 30)
• SENDBLUE_MAX_RETRIES (default: 3)
• SENDBLUE_REQUESTS_PER_SECOND (default: 5.0)

Quick Start

from backend.app.core.third_party_integrations.sendblue import client as sendblue
from backend.app.core.third_party_integrations.sendblue.api import messages

async def go():
    # Send
    msg = await messages.send_message(sendblue, data={
        "number": "+15551234567",
        "content": "Hello from Sendblue!",
    })

    # Get status
    status = await messages.get_message_status(sendblue, handle=msg.message_handle)

    # List
    lst = await messages.list_messages(sendblue, params={"limit": 50})

    # Retrieve
    one = await messages.retrieve_message(sendblue, message_id=msg.message_handle)

Endpoints Implemented

• Messages: send_message, get_message_status, list_messages, retrieve_message
• Contacts: count_contacts, create_contact, delete_contact, list_contacts, retrieve_contact, update_contact, verify_contact
• Contacts (bulk): bulk_create_contacts, bulk_delete_contacts
• Groups: modify_group, send_group_message
• Lookups: lookup_number
• Media Objects: upload_media
• Typing Indicators: send_typing_indicator

See modules under sendblue/api/.

Errors

Exceptions live in sendblue/api/_exceptions.py:

• SendblueAPIError
• SendblueAuthError
• SendblueRateLimitError
• SendblueValidationError
• SendblueNotFoundError
• SendblueServerError
• SendblueTimeoutError

Notes

• Media upload currently posts JSON. If multipart/form-data is needed, extend SendblueClient to support multipart.
• Consider adding idempotency keys for send endpoints if needed by your workflows.