MailcrateSDKs & Client Libraries
Call the API from any language with a plain HTTP client, or generate a typed client from the OpenAPI spec.
The Mailcrate API is JSON over HTTPS with one header, so any HTTP client in any language works. There is no official SDK package yet. Instead, the API publishes a complete OpenAPI spec, generated from its own source code on every change, and you can turn that into a typed client in a minute.
| You want to… | Use |
|---|---|
| Send a few requests from a script or a backend | Plain HTTP: fetch, requests, curl |
| A typed client with autocompletion | A client generated from the OpenAPI spec |
| Push React Email templates from a repository | The CLI (@mailcrate/cli) |
| Let an AI agent work in a workspace | The remote MCP server |
| Let a coding agent search these docs | Docs for AI Agents |
Plain HTTP
Every request needs the base URL, your key in Authorization, and a JSON body on writes:
curl -X POST https://api.mailcrate.io/public/sending/mail \
-H "Authorization: Api-Key $MAILCRATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contactEmail": "ada@example.com", "templateId": "welcome", "lane": "transactional"}'For anything beyond a script, wrap that in one function that adds the header, raises on errors and retries on 429. Errors and Rate Limits each have a copy-paste version.
The OpenAPI spec
The spec describes every public endpoint: paths, parameters, request and response bodies, the scope each needs (as x-mailcrate-scope) and the shared error shapes. It is what the API Reference pages are built from, and it is served as a file:
https://docs.mailcrate.io/openapi.jsonLoad it into Postman, Insomnia or Bruno to get a ready-made collection, or feed it to a client generator.
TypeScript
openapi-typescript turns the spec into types, and openapi-fetch is a small fetch wrapper that uses them. Paths, bodies and responses are all checked at compile time.
npm install openapi-fetch
npx openapi-typescript https://docs.mailcrate.io/openapi.json -o src/mailcrate.d.tsimport createClient from 'openapi-fetch';
import type { paths } from './mailcrate';
const mailcrate = createClient<paths>({
baseUrl: 'https://api.mailcrate.io',
headers: { Authorization: `Api-Key ${process.env.MAILCRATE_API_KEY}` },
});
const { data, error } = await mailcrate.POST('/public/sending/mail', {
body: {
contactEmail: 'ada@example.com',
templateId: 'password-reset',
lane: 'transactional',
data: { resetUrl: 'https://app.example.com/reset/8f2c' },
idempotencyKey: 'reset-8f2c',
},
});
if (error) throw new Error(String(error.message));
console.log(data.id, data.status); // typed as SendEmailResponsePython
openapi-python-client generates a package with a function per endpoint and a model per schema:
pip install openapi-python-client
openapi-python-client generate --url https://docs.mailcrate.io/openapi.json --output-path mailcrate_client
pip install ./mailcrate_clientimport os
from mailcrate_public_api_client import AuthenticatedClient
from mailcrate_public_api_client.api.sending import sending_send_mail
from mailcrate_public_api_client.models import SendEmailRequest
client = AuthenticatedClient(
base_url="https://api.mailcrate.io",
token=os.environ["MAILCRATE_API_KEY"],
prefix="Api-Key", # the API expects "Api-Key", not "Bearer"
)
delivery = sending_send_mail.sync(
client=client,
body=SendEmailRequest.from_dict({
"contactEmail": "ada@example.com",
"templateId": "password-reset",
"lane": "transactional",
"data": {"resetUrl": "https://app.example.com/reset/8f2c"},
}),
)
print(delivery.id, delivery.status)Other languages
Any OpenAPI 3 generator works: OpenAPI Generator covers Go, Java, PHP, Ruby, C# and many more. Two things to set in whatever you use:
- Authentication is an API key in the
Authorizationheader with theApi-Keyprefix. Generators that assumeBearerneed the prefix changed. - Regenerate when the API changes, to pick up new endpoints and fields. The spec is regenerated from the API source with every change to it.