Send an email
POST /emails
Queue one message for delivery and get its ID back.
Headers
Idempotency-Keystring1–256 characters, unique to this send. Replaying it inside 24 hours returns the original response instead of sending again.
Body
fromstringRequired unless
templatesupplies it. The sender, as an address orName <address>; its domain must be one this team has verified.tostring | string[]RequiredOne recipient or a list.
to,ccandbcctogether may not exceed 50 addresses.subjectstringRequired unless
templatesupplies it. Up to 998 bytes of UTF-8, on one line.htmlstringThe HTML body. Send
html,textor both; at least one is required.textstringThe plain-text body.
9 more fields (cc, bcc, reply_to, scheduled_at, headers, attachments, tags, template, topic_id)
ccstring | string[]Visible copies. Counts toward the recipient cap.
bccstring | string[]Blind copies. Counts toward the recipient cap.
reply_tostring | string[]Where replies go. Not counted toward the recipient cap.
scheduled_atstringAn ISO 8601 instant, or a phrase such as "in 2 hours", "tomorrow at 9am" or "next tuesday 9am" — phrases are read as UTC, and a day with no time means 09:00. Between 1 minute and 30 days from now.
headersobjectCustom message headers, name to value. Headers we own —
From,To,Cc,Bcc,Subject,Date,Message-ID,Return-Path, the MIME and DKIM headers, trace and authentication headers such asReceived,Sender,Authentication-Results,ARC-*andResent-*, delivery-control headers, and anyList-Unsubscribe*— are refused. Values may not contain control characters other than a tab.attachmentsobject[]Up to 100 items, each with a
filenameand exactly one ofcontent(base64) orpath(an https URL we fetch). Optionalcontent_type(a MIME type such asimage/png) andcontent_id(printable ASCII, no spaces or angle brackets).tagsobject[]Up to 50
{ name, value }pairs ofA-Z,a-z,0-9,_and-. A name is 1–252 characters and a value 1–256; a name may appear only once. Tags come back on the email and on every event for it, as an object.templateobject{ id, variables }.idis a template ID or alias; the template must be published, and its published version supplieshtml,textand, where the request omits them,subject,fromandreply_to. A send where neither setsfromorsubjectis422 missing_required_field. Cannot be combined withhtmlortext.variablesmaps each declared key to a string or number of at most 2000 characters; a missing key takes its fallback.topic_idstringReserved for subscription topics in a later phase.
Request
curl -X POST "https://api.rasket.com/emails" \
-H "Authorization: Bearer $RASKET_API_KEY" \
-H "User-Agent: acme-billing/1.0" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042" \
-d '{
"from": "Acme <orders@send.acme.example>",
"to": ["ronald.williams@example.com"],
"subject": "Your order has shipped",
"html": "<p>Order 1042 left the warehouse this morning.</p>"
}'const response = await fetch("https://api.rasket.com/emails", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
"User-Agent": "acme-billing/1.0",
"Content-Type": "application/json",
"Idempotency-Key": "order-1042",
},
body: JSON.stringify({
from: "Acme <orders@send.acme.example>",
to: ["ronald.williams@example.com"],
subject: "Your order has shipped",
html: "<p>Order 1042 left the warehouse this morning.</p>"
}),
});
const { id } = await response.json();import os
import requests
response = requests.post(
"https://api.rasket.com/emails",
headers={
"Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
"User-Agent": "acme-billing/1.0",
"Idempotency-Key": "order-1042",
},
json={
"from": "Acme <orders@send.acme.example>",
"to": ["ronald.williams@example.com"],
"subject": "Your order has shipped",
"html": "<p>Order 1042 left the warehouse this morning.</p>"
},
)
id = response.json()["id"]Response 200
{
"id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
}- A
200means we have accepted and durably recorded the message, not that it has been delivered. Delivery is reported by events. - Bodies are capped at 2 MB of
htmlandtextcombined. - Without an
Idempotency-Key, a retried request sends a second email.