Docs / Integrations / SDKs

Official SDKs

Typed clients in 5 languages today — Java, C#, Rust, Swift, and Dart via generated OpenAPI clients.

Machine translation available — choose your language in the top bar.

TypeScript / JavaScript

Install from npm. The package ships full TypeScript declarations and works in Node 18+, Bun, Deno (via npm:), and Edge runtimes.

install
npm install @mailgrid/sdk

The top-level Mailgrid class exposes namespaced resource groups:

Both @mailgrid/sdk and @inboxos/sdk resolve to the same package — the InboxOS import is a published alias.

full example — TypeScript
import { Mailgrid } from "@mailgrid/sdk";
// alias also works:
// import { InboxOS as Mailgrid } from "@inboxos/sdk";

const mg = new Mailgrid({
  apiKey: process.env.MAILGRID_KEY!,
  retry: { attempts: 3, backoff: "exponential" },
});

// ── send a plain email ──────────────────────────────────────
const sent = await mg.emails.send({
  from:    "hello@yourdomain.com",
  to:      "user@example.com",
  subject: "Welcome aboard",
  html:    "<p>Thanks for signing up!</p>",
});
console.log(sent.data.messageId);

// ── send from a template ────────────────────────────────────
await mg.emails.sendTemplate({
  templateId: "tmpl_welcome_v2",
  from:       "hello@yourdomain.com",
  to:         "user@example.com",
  variables:  { firstName: "Ada", planName: "Pro" },
});

// ── per-request AbortController timeout ────────────────────
const ac = new AbortController();
setTimeout(() => ac.abort(), 5000);
await mg.emails.send({ ...payload, signal: ac.signal });

// ── error handling ──────────────────────────────────────────
try {
  await mg.emails.send(payload);
} catch (err) {
  if (err instanceof Mailgrid.APIError) {
    console.error(err.status, err.code, err.message);
  }
}

Python

Requires Python 3.9+. Ships both a synchronous client and an asyncio-native async client.

install
pip install mailgrid

Both import paths resolve identically — use whichever fits your codebase:

sync send — Python
from mailgrid import Mailgrid
# alias also works:
# from inboxos import InboxOS as Mailgrid

mg = Mailgrid(api_key="mb_live_...")

resp = mg.emails.send(
    from_="hello@yourdomain.com",
    to="user@example.com",
    subject="Hello from Python",
    text="Plain text body.",
)
print(resp.data.message_id)
async send — Python
import asyncio
from mailgrid import AsyncMailgrid

async def main():
    mg = AsyncMailgrid(api_key="mb_live_...")
    resp = await mg.emails.send(
        from_="hello@yourdomain.com",
        to="user@example.com",
        subject="Async send",
        html="<p>Sent with asyncio.</p>",
    )
    print(resp.data.message_id)

asyncio.run(main())
error handling — Python
from mailgrid import Mailgrid, APIError

mg = Mailgrid(api_key="mb_live_...")

try:
    mg.emails.send(from_="bad", to="also-bad", subject="")
except APIError as e:
    print(e.status, e.code, e.message)

Go

Requires Go 1.21+. The module path is github.com/mailgrid/sdk-go.

install
go get github.com/mailgrid/sdk-go
send with retry — Go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/mailgrid/sdk-go/mailgrid"
)

func main() {
    mg := mailgrid.New(
        "mb_live_...",
        mailgrid.WithBaseURL("https://api.mailgrid.space"),
        mailgrid.WithRetry(3),
    )

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    resp, err := mg.Emails.Send(ctx, &mailgrid.SendEmailRequest{
        From:    "hello@yourdomain.com",
        To:      []string{"user@example.com"},
        Subject: "Hello from Go",
        Text:    "Plain text body.",
    })
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println(resp.Data.MessageID)
}

Ruby

Requires Ruby 3.1+. The gem follows a fluent resource pattern consistent with Stripe's Ruby SDK.

install
gem install mailgrid
send email — Ruby
require "mailgrid"

mg = Mailgrid::Client.new(api_key: "mb_live_...")

# Send a plain email
resp = mg.emails.send(
  from:    "hello@yourdomain.com",
  to:      "user@example.com",
  subject: "Hello from Ruby",
  text:    "Plain text body."
)
puts resp.data.message_id

# Resource pattern — list domains
domains = mg.domains.list
domains.each { |d| puts d.name, d.status }

# Send from a template
mg.emails.send_template(
  template_id: "tmpl_welcome_v2",
  from:        "hello@yourdomain.com",
  to:          "user@example.com",
  variables:   { first_name: "Ada" }
)

PHP

Requires PHP 8.1+ with the curl extension. The package uses Guzzle 7 as its HTTP client.

install
composer require mailgrid/mailgrid
send email — PHP
<?php

use Mailgrid\Client;
use Mailgrid\Exceptions\APIException;

$mg = new Client(apiKey: 'mb_live_...');

try {
    $resp = $mg->emails->send([
        'from'    => 'hello@yourdomain.com',
        'to'      => 'user@example.com',
        'subject' => 'Hello from PHP',
        'html'    => '<p>Sent via the PHP SDK.</p>',
    ]);

    echo $resp->data->messageId . "\n";
} catch (APIException $e) {
    echo 'Error ' . $e->getStatus()
       . ': ' . $e->getMessage() . "\n";
}

Generated clients

Java, Kotlin, C#, Rust, Swift, and Dart clients are generated directly from the OpenAPI spec bundled in the repo at packages/openapi/openapi.yaml. Use the OpenAPI Generator CLI:

generate a client
npx @openapitools/openapi-generator-cli generate \
  -i packages/openapi/openapi.yaml \
  -g <lang> \
  -o build/<lang>

Replace <lang> with the generator name for your target language:

Language Generator name Output dir
Java java build/java
Kotlin kotlin build/kotlin
C# csharp build/csharp
Rust rust build/rust
Swift swift5 build/swift
Dart dart build/dart
Regenerating after API updates

Run the generate command again after pulling a new version of the spec. The generated clients are not checked into the repo — add build/ to your .gitignore.

OpenAPI spec

The canonical spec is OpenAPI 3.1 and is available in two locations:

The live endpoint always reflects the current production API version and is suitable for use as the -i input to the generator in CI pipelines:

generate from live spec
npx @openapitools/openapi-generator-cli generate \
  -i https://api.mailgrid.space/openapi.json \
  -g java \
  -o build/java

The spec is published as OpenAPI version 3.1. It includes full request/response schemas, authentication details (BearerAuth), and per-operation x-mailgrid-* extensions used by the MCP tool manifest.

← Previous
Integrations
Next →
Webhooks