API reference
Send an email
Send an email using a published template and your application’s data.
Request
POST /api/v1/emails
| Field | Required | Description |
|---|---|---|
to |
Yes | One email address, up to 255 characters. |
template |
Yes | Template key in this project, up to 100 characters. Use lowercase letters, numbers, _, or -; start with a letter or number. |
data |
Yes | Object of template variables. Use {} when there are no variables. |
locale |
No | Published language tag, such as ja or en-gb. Omit to use the template’s default language. |
version |
No | Published version number. Defaults to the latest version. |
attachments |
No | Files to include with this email. |
Example request
Replace your-template with your published template’s key and data with its variables.
curl https://sendery.co/api/v1/emails \
-H "Authorization: Bearer $SENDERY_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"to": "[email protected]",
"template": "your-template",
"data": {"name": "Alex", "action_url": "https://example.com/start"}
}'require 'vendor/autoload.php';
use Sendery\Client;
$sendery = new Client(getenv('SENDERY_API_KEY'));
$receipt = $sendery->send(
to: '[email protected]',
template: 'your-template',
data: ['name' => 'Alex', 'action_url' => 'https://example.com/start'],
);
echo $receipt['id'];import { Sendery } from '@sendery/sdk';
const apiKey = process.env.SENDERY_API_KEY;
if (!apiKey) throw new Error('Set SENDERY_API_KEY on your server.');
const sendery = new Sendery(apiKey);
const receipt = await sendery.send({
to: '[email protected]',
template: 'your-template',
data: { name: 'Alex', action_url: 'https://example.com/start' },
});
console.log(receipt.id);package main
import (
"context"
"fmt"
"log"
"os"
"github.com/sendery-co/sendery-go"
)
func main() {
client, err := sendery.NewClient(os.Getenv("SENDERY_API_KEY"))
if err != nil {
log.Fatal(err)
}
receipt, err := client.Send(context.Background(), sendery.SendEmailInput{
To: "[email protected]",
Template: "your-template",
Data: map[string]any{
"name": "Alex",
"action_url": "https://example.com/start",
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(receipt.ID)
}import os
from sendery import Sendery
sendery = Sendery(os.environ["SENDERY_API_KEY"])
receipt = sendery.send(
to="[email protected]",
template="your-template",
data={"name": "Alex", "action_url": "https://example.com/start"},
)
print(receipt["id"])import co.sendery.Sendery;
import java.util.Map;
public class SendEmail {
public static void main(String[] args) {
var sendery = new Sendery(System.getenv("SENDERY_API_KEY"));
var receipt = sendery.send("[email protected]", "your-template", Map.of(
"name", "Alex",
"action_url", "https://example.com/start"
));
System.out.println(receipt.id());
}
}import co.sendery.Sendery
fun main() {
val sendery = Sendery(System.getenv("SENDERY_API_KEY"))
val receipt = sendery.send("[email protected]", "your-template", mapOf(
"name" to "Alex",
"action_url" to "https://example.com/start"
))
println(receipt.id())
}Response
A new email returns 202 with its id and status. Repeating an accepted request with the same Idempotency-Key and payload returns 200, the original ID, and the current status. Draft edits and later publications do not change an accepted email.
{
"id": "35a6b227-1748-412e-8651-430492201670",
"status": "queued",
"sandbox_url": "https://sendery.co/en/app/projects/5656/activity/35a6b227-1748-412e-8651-430492201670"
}Variables and limits
Include your template’s variables in data. Missing text values appear blank; dynamic content such as images is omitted when its value is missing. Enable Strictly enforce API requests in Project settings to reject missing variables. Variables used only in hidden blocks can always be omitted.
Values can be strings, numbers, booleans, or arrays of objects for Line Items. null and nested objects are not supported.
| Limit | Maximum |
|---|---|
| JSON request body, including encoded attachments | 8 MB (8,388,608 bytes) |
| Attachments per email | 10 |
| Combined file size before base64 encoding | 5 MB (5,242,880 bytes) |
Combined JSON data |
200,000 bytes |
Variables in data |
50 |
| Scalar value | 65,536 bytes |
| Rows per array | 100 |
| Fields per row | 10 |
| Value in a row | 2,000 bytes |
Oversized rendered emails return 422; reduce repeated content or long variable values.
Sender and content
Configure the sender in your project and the subject and body in your template. The request accepts only to, template, data, locale, version, and attachments. Raw html, subject, from, cc, bcc, and multiple recipients are not supported.
Send a specific version
Set version to a number from your template’s published history. Omit it for the latest version. Versions that are no longer in your history return 422 validation_error.
{
"to": "[email protected]",
"template": "your-template",
"data": {
"name": "Alex",
"action_url": "https://example.com/start"
},
"version": 3
}Attachments
Attach up to 10 files, totaling 5 MB before base64 encoding. Add an attachments array to your send request:
| Field | Required | Description |
|---|---|---|
filename |
Yes | File name shown to the recipient, without a directory path. |
content |
Yes | Base64-encoded file contents, without whitespace or a data: prefix. |
content_type |
No | MIME type, such as application/pdf. |
Send file contents rather than URLs. Inline attachments and certain file types, including executables, are not supported. Attachments are not available in email history.
When retrying a send, keep the attachments and idempotency key unchanged.
curl https://sendery.co/api/v1/emails \
-H "Authorization: Bearer $SENDERY_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: your-idempotency-key' \
-d '{
"to": "[email protected]",
"template": "your-template",
"data": {"name": "Alex", "action_url": "https://example.com/start"},
"attachments": [{
"filename": "document.txt",
"content": "SGVsbG8sIEFseCE=",
"content_type": "text/plain"
}]
}'