Installation

bash

pip install harbur

Or using Poetry / Pipenv:

bash

poetry add harbur
# or
pipenv install harbur

Basic Usage

Initialize the client. It automatically detects HARBUR_API_KEY from your environment.

send_email.py

from harbur import Harbur

# Automatically reads HARBUR_API_KEY from environment
client = Harbur()

response = client.emails.send(
    from_address="support@yourdomain.com",
    to="user@example.com",
    subject="Welcome to Harbur",
    html="<h1>Welcome aboard!</h1><p>Your transactional email was delivered instantly.</p>",
    text="Welcome aboard! Your transactional email was delivered instantly.",
)

print("Dispatched:", response["id"])

Note

Store your API key in an environment variable. Never hardcode credentials in source files or commit them to version control.

CC, BCC & Custom Reply-To

Easily send copies to teams, hidden audit archives, or direct replies to customer support.

advanced_send.py

from harbur import Harbur

client = Harbur()

response = client.emails.send(
    from_address="support@yourdomain.com",
    to=["primary@example.com"],
    cc=["manager@example.com"],
    bcc=["archive@example.com"],
    reply_to="helpdesk@yourdomain.com",
    subject="Order #1042 Confirmation",
    html="<p>Your order has been confirmed.</p>",
)

File Attachments

Pass file bytes or base64 strings to attach downloadable receipts, reports, or invoices.

send_attachment.py

from harbur import Harbur

client = Harbur()

with open("invoice.pdf", "rb") as f:
    pdf_bytes = f.read()

response = client.emails.send(
    from_address="support@yourdomain.com",
    to="client@example.com",
    subject="Your Invoice & Statement",
    html="<p>Your invoice is attached below.</p>",
    attachments=[
        {
            "filename": "invoice_1042.pdf",
            "content": pdf_bytes,  # Raw bytes or base64 string
            "content_type": "application/pdf",
        }
    ]
)

FastAPI Example

main.py

from fastapi import FastAPI, HTTPException
from harbur import Harbur, HarburError

app = FastAPI()
client = Harbur()

@app.post("/send-welcome")
async def send_welcome(email: str, name: str):
    try:
        res = client.emails.send(
            from_address="welcome@yourdomain.com",
            to=email,
            subject=f"Welcome {name}!",
            html=f"<h1>Welcome {name}!</h1>",
        )
        return {"success": True, "id": res["id"]}
    except HarburError as e:
        raise HTTPException(status_code=500, detail=str(e))