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. |
Example request
Use the key and variables from your published template. The example uses welcome, name, and action_url.
curl https://sendery.co/api/v1/emails \
-H "Authorization: Bearer $SENDERY_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Idempotency-Key: welcome-123' \
-d '{
"to": "[email protected]",
"template": "welcome",
"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: 'welcome',
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: 'welcome',
data: { name: 'Alex', action_url: 'https://example.com/start' },
});
console.log(receipt.id);import os
from sendery import Sendery
sendery = Sendery(os.environ["SENDERY_API_KEY"])
receipt = sendery.send(
to="[email protected]",
template="welcome",
data={"name": "Alex", "action_url": "https://example.com/start"},
)
print(receipt["id"])import co.sendery.Sendery;
import java.util.Map;
public class SendWelcome {
public static void main(String[] args) {
var sendery = new Sendery(System.getenv("SENDERY_API_KEY"));
var receipt = sendery.send("[email protected]", "welcome", 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]", "welcome", 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"
}Variables and limits
Supply every variable used by the template. Values can be strings, numbers, booleans, or lists of objects for Line Items blocks. null and nested objects are not supported. Empty strings and whitespace are preserved.
| Limit | Maximum |
|---|---|
| JSON request body | 64 KiB (65,536 bytes) |
Variables in data |
50 |
| Scalar value | 10,000 bytes |
| Rows per array | 100 |
| Fields per row | 10 |
| Value in a row | 2,000 bytes |
Line Items blocks require specific fields and allow up to 20 adjustment rows; see the line items guide. 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, and locale. Raw html, subject, from, attachments, cc, bcc, and multiple recipients are not supported.