API

Email API for transactional and bulk email

Send transactional and bulk email from your own SMTP, SendGrid, Mailgun, Postmark or SES account, with a delivery log.

What it does

The Takelan Email API sends email for your apps. You write a template once, then call one endpoint with a recipient and a few variables. Takelan renders the message, sends it and records the result in a searchable log.
It solves a problem every product team hits: email is never "just one call". You need templates, a way to preview them, a sending provider, a log to answer "did the customer get it?", and a way to send a few hundred at once without writing a queue. This API gives you those parts behind one key.
You choose how mail leaves. Use the platform default, or register your own mail server. Supported provider types are plain SMTP, SendGrid, Mailgun, Postmark and Amazon SES. Provider secrets are stored encrypted on the server. You can also register Proxmox Mail Gateway hosts, set a default one, test it, and match a sent message to the gateway log line.
Mail can come in as well. Inbound mailboxes accept messages from a gateway webhook (signed with HMAC-SHA256) or by polling an IMAP mailbox. Messages are threaded, and a thread can be turned into a ticket in Takelan Customer Desk.
Send as a user with a normal token, or as an app with a service token or API key. Tenant comes from the token, never from the request body, so one customer cannot send as another. Over the limit, you get a 429 with a Retry-After header. Exact numbers vary by environment, so we do not publish one here.
Affordable by design. Start free* inside platform limits, and bring your own provider so you are not paying twice for sending. *Free within platform limits; usage beyond limits may be charged to maintain the platform. Connected ShadowCradle organizations can switch on Takelan SSO and these free* services with one switch. Airgap licences work without any Takelan connection.

See how it works

One call, your choice of route

Your app sends a template name and variables. The API renders and sends it through the platform route or through your own mail provider, and records the result in a searchable log.

Mail coming in

Inbound mailboxes accept messages from a signed gateway webhook or by polling an IMAP mailbox. Messages are threaded, and a thread can become a Customer Desk ticket.

Example use cases

Receipts, resets and welcome mail

A SaaS team keeps "welcome", "password reset" and "invoice" templates in one place. The app calls /send with the template name and variables. Marketing can edit the wording without a deploy.

Send through the provider you already pay for

A small agency registers its Postmark server once. Every app it builds then sends through that server, and the delivery log still lives in Takelan.

Monthly notices to a customer list

An MSP sends a maintenance notice to a client list with the bulk endpoint. Each recipient can carry its own variables, such as name and server. The result lists which addresses worked and which failed.

Mail gateway visibility

An IT team that runs Proxmox Mail Gateway registers it, sets it as the default and tests it. For any sent message it can match the gateway log to see what happened after it left.

Shared support inbox to tickets

A support mailbox is polled over IMAP, or fed by a gateway webhook. Replies are grouped into threads, and one call turns a thread into a ticket.

Raw messages with your own threading

A sales tool sends a plain message with its own Message-ID, In-Reply-To and References headers so replies stay in one thread in the recipient's mail client.

Try it

Send a templated email

curl -X POST https://app.takelan.com/api/v1/email/send \
  -H "X-API-Key: $TAKELAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "welcome",
    "to_email": "sam@example.com",
    "to_name": "Sam",
    "template_variables": { "first_name": "Sam", "plan": "Starter" }
  }'

# Response (abridged, fictional)
# {
#   "id": "8f2c...e1",
#   "to_email": "sam@example.com",
#   "template_name": "welcome",
#   "status": "sent"
# }

Add "mail_server_id" to send through one of your own registered mail servers. Without it the tenant default is used, and then the platform default.

Bulk send with per-recipient variables

curl -X POST https://app.takelan.com/api/v1/email/send/bulk \
  -H "X-API-Key: $TAKELAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "maintenance-notice",
    "batch_name": "november-window",
    "default_variables": { "window": "Sat 02:00-04:00" },
    "recipients": [
      { "email": "ops@client-a.example", "variables": { "client": "Client A" } },
      { "email": "it@client-b.example",  "variables": { "client": "Client B" } }
    ]
  }'

# Response (abridged, fictional)
# { "batch_name": "november-window", "total_recipients": 2, "successful": 2, "failed": 0 }

One request takes up to 1,000 recipients, as set in the request schema.

Endpoints

POST /api/v1/email/send Send one email from a template.
POST /api/v1/email/send-message Send a raw message with your own Message-ID, In-Reply-To and References.
POST /api/v1/email/send/bulk Send a template to a list of recipients, each with its own variables.
GET /api/v1/email/products List the products (sending identities) you registered.
POST /api/v1/email/products/register Register a product that sends mail.
POST /api/v1/email/templates Create a template.
GET /api/v1/email/templates List templates.
PUT /api/v1/email/templates/{template_id} Edit a template.
POST /api/v1/email/templates/{template_id}/duplicate Copy a template, including a starter template.
POST /api/v1/email/templates/preview Render a template with variables without sending.
GET /api/v1/email/samples Browse starter templates. Fetch one by key, or preview it.
GET /api/v1/email/emails Search the sent-mail log.
GET /api/v1/email/emails/{email_id} One message and its delivery status.
POST /api/v1/email/emails/{email_id}/match-gateway-log Find the matching line in a mail gateway log.
GET /api/v1/email/stats Delivery statistics.
GET /api/v1/email/stats/timeseries Statistics over time.
GET /api/v1/email/reports Email reports.
GET /api/v1/email/servers/providers List provider types (SMTP, SendGrid, Mailgun, Postmark, SES) and the fields each needs.
POST /api/v1/email/servers Register your own mail server.
GET /api/v1/email/servers List your mail servers.
PATCH /api/v1/email/servers/{server_id} Change a mail server.
POST /api/v1/email/servers/{server_id}/test Test the connection.
POST /api/v1/email/servers/{server_id}/send-test Send a test message through it.
POST /api/v1/email/gateways Register a Proxmox Mail Gateway.
GET /api/v1/email/gateways List gateways.
POST /api/v1/email/gateways/{gateway_id}/set-default Make a gateway the default.
POST /api/v1/email/gateways/{gateway_id}/test Test a gateway.
POST /api/v1/email/inbound Gateway webhook for inbound mail. Signed with X-Inbound-Signature (HMAC-SHA256).
POST /api/v1/email/inbound/mailboxes Create an inbound mailbox (gateway webhook or IMAP polling).
POST /api/v1/email/inbound/mailboxes/{mailbox_id}/poll Poll an IMAP mailbox now.
GET /api/v1/email/inbound List inbound messages.
GET /api/v1/email/inbound/threads/{thread_ref} Read a whole thread.
POST /api/v1/email/inbound/{message_id}/convert-to-ticket Turn an inbound message into a Customer Desk ticket.

MCP

Available as tools through /mcp/utils. Reading templates, the sent log and stats works with a read-only key. Sending mail is a write, so it is off by default: it needs the tenant's writes switch (Settings, MCP / AI agents) and a key that is not read-only. Routes that touch provider secrets are marked sensitive, and the inbound webhook is not exposed as a tool. About MCP

Common questions

how to send transactional email with an API

Create a template with POST /api/v1/email/templates, then call POST /api/v1/email/send with the template name, the recipient and your variables. Use the X-API-Key header. The result is saved in the sent-mail log.

can I use my own SMTP server, SendGrid, Mailgun, Postmark or SES with the Takelan Email API

Yes. Register a mail server of type SMTP, SendGrid, Mailgun, Postmark or SES, then pass its mail_server_id when you send. Without one, the tenant default server is used, then the platform default. Provider secrets are stored encrypted on the server.

how do I send bulk email from an API with different variables per person

POST /api/v1/email/send/bulk takes a template, shared default_variables and a list of recipients, each with its own variables. One request holds up to 1,000 recipients. The response says how many succeeded and failed, per address.

does it work with Proxmox Mail Gateway

Yes. You can register PMG hosts, set a default, test one, and match a sent message against the gateway log. Inbound mail from a gateway can also be delivered to a signed webhook.

how do I receive inbound email in an app

Create an inbound mailbox. Either point your gateway at the signed webhook (X-Inbound-Signature, HMAC-SHA256 of the raw body) or let Takelan poll an IMAP mailbox. Messages are threaded, and a repeat delivery of the same Message-ID creates nothing new.

how do I check if an email was delivered via API

Search GET /api/v1/email/emails or fetch one message by id. For aggregate numbers, use /stats and /stats/timeseries. We do not publish delivery-rate figures, because they depend on the provider you choose.

what authentication does the email API use

Send an X-API-Key header, or a Bearer token from Takelan SSO. App-to-app callers can use a service token. The tenant comes from the credential, so one tenant cannot send as another.

is the Takelan email API free

It is affordable by design. You can start free* within platform limits, and bringing your own provider avoids paying twice for sending. *Free within platform limits; usage beyond limits may be charged to maintain the platform.

All API families | Takelan Utilities & APIs | Pricing