> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailbreeze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SDK Overview
> Official MailBreeze client libraries
MailBreeze provides official SDKs for six programming languages, each offering the same 23 endpoints across 5 resources.
## Installation
```bash npm theme={null}
npm install mailbreeze
```
```bash pip theme={null}
pip install mailbreeze
```
```bash gradle theme={null}
implementation("com.mailbreeze:mailbreeze-java:0.1.0")
```
```bash go theme={null}
go get github.com/MailBreeze/mailbreeze-go
```
```bash composer theme={null}
composer require mailbreeze/mailbreeze-php
```
```bash cargo theme={null}
cargo add mailbreeze
```
## Quick Comparison
| Feature | JavaScript | Python | Java | Go | PHP | Rust |
| ----------- | --------------- | ------------ | ----------------- | --------------- | --------------------------- | ------------ |
| Package | `mailbreeze` | `mailbreeze` | `mailbreeze-java` | `mailbreeze-go` | `mailbreeze/mailbreeze-php` | `mailbreeze` |
| Min Version | Node 20+ | Python 3.10+ | Java 17+ | Go 1.21+ | PHP 8.2+ | Rust 1.70+ |
| Async | Native Promise | async/await | Sync | Context | Sync | async/await |
| HTTP Client | Native fetch | httpx | OkHttp | net/http | Guzzle | reqwest |
| Type Safety | Full TypeScript | Pydantic | Jackson | Struct types | PHPDoc | Serde |
## Resources
All SDKs provide access to the same 5 resources:
| Resource | Description | Methods |
| ---------------- | ----------------------- | ------------------------------------------------------- |
| **emails** | Send and manage emails | `send`, `list`, `get`, `stats` |
| **attachments** | Upload file attachments | `createUpload`, `confirm` |
| **lists** | Manage contact lists | `create`, `list`, `get`, `update`, `delete`, `stats` |
| **contacts** | Manage list contacts | `create`, `list`, `get`, `update`, `delete`, `suppress` |
| **verification** | Verify email addresses | `verify`, `batch`, `get`, `list`, `stats` |
## Common Features
All official SDKs include:
Exponential backoff for transient failures (5xx, rate limits)
Full type definitions for all params and responses
Typed exceptions with error codes and messages
Automatic redaction of keys in debug output
## Client Initialization
```typescript JavaScript theme={null}
import { MailBreeze } from "mailbreeze";
const mailbreeze = new MailBreeze({
apiKey: process.env.MAILBREEZE_API_KEY,
// Optional configuration
baseUrl: "https://api.mailbreeze.com", // Custom API URL
timeout: 30000, // Request timeout in ms
});
```
```python Python theme={null}
from mailbreeze import MailBreeze
client = MailBreeze(
api_key=os.environ["MAILBREEZE_API_KEY"],
# Optional configuration
base_url="https://api.mailbreeze.com",
timeout=30.0,
)
```
```java Java theme={null}
import com.mailbreeze.MailBreeze;
MailBreeze mailbreeze = MailBreeze.builder()
.apiKey(System.getenv("MAILBREEZE_API_KEY"))
// Optional configuration
.baseUrl("https://api.mailbreeze.com")
.timeout(Duration.ofSeconds(30))
.build();
```
```go Go theme={null}
import mailbreeze "github.com/MailBreeze/mailbreeze-go"
client := mailbreeze.NewClient(
os.Getenv("MAILBREEZE_API_KEY"),
// Optional configuration
mailbreeze.WithBaseURL("https://api.mailbreeze.com"),
mailbreeze.WithTimeout(30 * time.Second),
)
```
```php PHP theme={null}
use MailBreeze\MailBreeze;
$mailbreeze = new MailBreeze(
getenv('MAILBREEZE_API_KEY'),
// Optional configuration
[
'base_url' => 'https://api.mailbreeze.com',
'timeout' => 30,
]
);
```
```rust Rust theme={null}
use mailbreeze::MailBreeze;
let client = MailBreeze::builder("sk_live_xxx")
// Optional configuration
.base_url("https://api.mailbreeze.com")
.timeout(Duration::from_secs(30))
.build()?;
```
## Error Handling
```typescript JavaScript theme={null}
import { MailBreeze, MailBreezeError } from "mailbreeze";
try {
await mailbreeze.emails.send({ ... });
} catch (error) {
if (error instanceof MailBreezeError) {
console.log(error.code); // "VALIDATION_ERROR"
console.log(error.message); // "Invalid email format"
console.log(error.status); // 400
}
}
```
```python Python theme={null}
from mailbreeze import MailBreeze, MailBreezeError
try:
await client.emails.send(...)
except MailBreezeError as e:
print(e.code) # "VALIDATION_ERROR"
print(e.message) # "Invalid email format"
print(e.status) # 400
```
```java Java theme={null}
import com.mailbreeze.exceptions.*;
try {
mailbreeze.emails().send(params);
} catch (MailBreezeException e) {
System.out.println(e.getCode()); // "VALIDATION_ERROR"
System.out.println(e.getMessage()); // "Invalid email format"
System.out.println(e.getStatusCode()); // 400
}
```
```go Go theme={null}
import "errors"
_, err := client.Emails.Send(ctx, params)
if err != nil {
var mbErr *mailbreeze.Error
if errors.As(err, &mbErr) {
fmt.Println(mbErr.Code) // "VALIDATION_ERROR"
fmt.Println(mbErr.Message) // "Invalid email format"
fmt.Println(mbErr.Status) // 400
}
}
```
```php PHP theme={null}
use MailBreeze\Exceptions\MailBreezeException;
try {
$mailbreeze->emails()->send([...]);
} catch (MailBreezeException $e) {
echo $e->getCode(); // "VALIDATION_ERROR"
echo $e->getMessage(); // "Invalid email format"
echo $e->getStatus(); // 400
}
```
```rust Rust theme={null}
match client.emails.send(¶ms).await {
Ok(email) => println!("Sent: {}", email.id),
Err(mailbreeze::Error::Api { code, message, status }) => {
println!("Code: {}", code); // "VALIDATION_ERROR"
println!("Message: {}", message); // "Invalid email format"
println!("Status: {}", status); // 400
}
Err(e) => println!("Other error: {}", e),
}
```
## Choose Your Language
Full TypeScript support, ESM + CJS
Async with Pydantic models
Builder pattern with Jackson
Idiomatic API with context support
PSR-4 with Guzzle HTTP
Async with Tokio + Serde