Help › For developers
Sending API
Send email from your own apps and websites, from your own addresses, with your own templates.
Your apps, websites and scripts can send email from your organization's addresses with one HTTPS request: order confirmations, password resets, contact forms, reports. The emails go out the same way as the ones you write in SendHaste.
| Request | What it does |
|---|---|
POST https://sendhaste.com/api/v1/emails | Sends one email: your own content, or one of your templates with values. |
GET https://sendhaste.com/api/v1/templates | Lists the emails connected to templates, and the values each one uses. |
GET https://sendhaste.com/api/v1/senders | Lists the addresses the key may send from. |
GET https://sendhaste.com/api/v1/openapi.json | The whole API as an OpenAPI 3.1 file, for Postman, code generators and other developer tools. No key needed. |
1. Make an API key
- An Org Super Admin opens Settings → API keys.
- Click Make an API key, give it a name (e.g. Website contact form) and choose Sends from: any address on your domains, any address on one domain, or one address only. Click Make key.
- A window shows the new key, with its name and the address it sends from. Click Copy, then Done. The key starts with
sh_and is shown only once: if it's lost, revoke it and make a new one.
For automated emails from one domain (order confirmations, alerts, reports), open Settings → Domains, pick the domain and click Make an API key for yourdomain.com: the key may send from any address on that domain and no other. Add a mailbox for the sending address first, like noreply@yourdomain.com. Only the sender is limited: the emails can go to anyone, at your company or outside it.
Keep the key on your server, in a setting or environment variable. Never put it in a web page, a mobile app or a public code repository: anyone who has it can send email as you. If it leaks, click Revoke: it stops working at once.
2. Send an email
Send a POST request to https://sendhaste.com/api/v1/emails, with the key in the Authorization: Bearer sh_… header and the email as JSON:
curl https://sendhaste.com/api/v1/emails \
-H "Authorization: Bearer sh_your_key" \
-H "Content-Type: application/json" \
-d '{
"from": "Your Company <info@yourcompany.com>",
"to": ["client@example.com"],
"subject": "Your booking is confirmed",
"html": "<p>Thank you! See you on <b>Monday</b>.</p>",
"text": "Thank you! See you on Monday."
}'const res = await fetch("https://sendhaste.com/api/v1/emails", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SENDHASTE_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
from: "Your Company <info@yourcompany.com>",
to: "client@example.com",
subject: "Your booking is confirmed",
text: "Thank you! See you on Monday.",
}),
});
const result = await res.json(); // { id, from, to, recipients } or { error: { code, message } }3. Send one of your templates
Instead of writing the email in your code, design it once in Templates and let your website send it by name: a welcome email, a password reset, an order confirmation. To change the email later, edit the template or connect the name to another one; nothing changes on the website.
- In Templates, design the email. Where a value from your website goes, type
{{params.first_name}}; after a bar, what to use when it's missing:{{params.first_name|there}}. It works in the subject, the text, and in button and link addresses. - An Org Super Admin opens Settings → API keys, and under Emails your websites send clicks Connect an email, types an Email name (e.g.
welcome), picks the Template, picks under Sent from every address on your domains, one domain or one address, and clicks Connect. - Under Send a test, send it to yourself with some values to see how it looks.
- Your website sends
templatewith the name, andparamswith the values. The template's subject is used, unless you send asubject.
curl https://sendhaste.com/api/v1/emails \
-H "Authorization: Bearer sh_your_key" \
-H "Content-Type: application/json" \
-d '{
"from": "Your Shop <hello@yourshop.com>",
"to": "aysel@example.com",
"template": "welcome",
"params": { "first_name": "Aysel", "verify_url": "https://yourshop.com/verify?t=8f2c" }
}'- The built-in tags work too:
{{first_name}},{{name}},{{company}},{{email}}.{{email}}is the first To address; the names come fromparamswhen you send them, else from the person's contact in SendHaste. - Values are put in as text: HTML in a value shows as written, and a link value must start with https://, http:// or mailto:.
- A missing value without a fallback is left empty, so test with Send a test first.
Example: a welcome email for new sign-ups
- Make a template called Welcome, with the subject
Welcome, {{params.first_name|there}}!, a headingHi {{params.first_name|there}}and a button to{{params.verify_url}}. - Connect it as
welcomein Settings → API keys, and make a key that sends from your address. - Put the key in your website's settings (for example an environment variable
SENDHASTE_API_KEY). - Where your website saves a new user, send the request. Pick your language:
await fetch("https://sendhaste.com/api/v1/emails", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SENDHASTE_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
from: "Your Shop <hello@yourshop.com>",
to: user.email,
template: "welcome",
params: { first_name: user.firstName, verify_url: verifyUrl },
}),
});$ch = curl_init("https://sendhaste.com/api/v1/emails");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SENDHASTE_API_KEY"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode([
"from" => "Your Shop <hello@yourshop.com>",
"to" => $user["email"],
"template" => "welcome",
"params" => ["first_name" => $user["first_name"], "verify_url" => $verifyUrl],
]),
]);
$result = json_decode(curl_exec($ch), true);import os, requests
requests.post(
"https://sendhaste.com/api/v1/emails",
headers={"Authorization": f"Bearer {os.environ['SENDHASTE_API_KEY']}"},
json={
"from": "Your Shop <hello@yourshop.com>",
"to": user.email,
"template": "welcome",
"params": {"first_name": user.first_name, "verify_url": verify_url},
},
timeout=10,
)Send it after the user is saved, and don't let a failed email stop the sign-up: log the error and carry on. The answer's id helps us find an email if you write to us.
List your templates
GET https://sendhaste.com/api/v1/templates with the same key answers with the emails connected in Settings → API keys, and the values each one uses:
{"data": [{"name": "welcome", "template_name": "Welcome", "subject": "Welcome, {{params.first_name|there}}!", "params": ["first_name", "verify_url"], "updated_at": "…", "scope": "domain", "for": "yourshop.com"}]}| Field | What it is |
|---|---|
name | What to send as template. |
template_name | The template's name in SendHaste. |
subject | The template's subject, with its tags not yet filled in. |
params | The {{params.…}} names the template uses: send these in params. |
updated_at | When the template was last changed. |
scope | Who it's connected for: organization (every address on your domains), domain or address. |
for | The domain or the address it's connected for; null for the whole organization. |
Your code can call this at start-up, or in a test, to check that every email it sends is connected and gets all its values.
Each email is connected for every address on your domains, for one domain or for one address (Sent from). A key lists and sends only the emails for the addresses it may send from, so websites on different domains each see their own. The same name can be connected for each: an email sent from info@yourshop.com uses the one for that address, else the one for its domain, else the organization's.
List your addresses
GET https://sendhaste.com/api/v1/senders with the same key answers with the addresses it may send from. Use it to let people pick the From address instead of writing one into your code.
{"data": [{"address": "info@yourcompany.com"}, {"address": "noreply@yourcompany.com"}], "domains": [{"domain": "yourcompany.com"}]}| Field | What it is |
|---|---|
data | Every address the key may send from that has a mailbox: the one address it was made for, every mailbox on its domain, or every mailbox on your domains. |
domains | The domains the key may send from. Empty for a key made for one address. |
Every From address needs a mailbox of its own in SendHaste. An address added to a mailbox under Also receives can't be used, and neither can catchall@. For a sending-only address like noreply@yourdomain.com, add a mailbox for it in Settings → Domains; it shows up in data at once.
The fields
| Field | Required | What it is |
|---|---|---|
from | yes | One of your addresses, with a name if you like: Your Company <info@yourcompany.com>. It must have a mailbox in SendHaste. |
to | yes | An address, or a list of addresses. |
cc, bcc | no | An address, or a list. Bcc recipients aren't shown to the others. |
reply_to | no | Where replies go, if not to the From address. |
subject | yes, unless template | The subject line. With a template, it replaces the template's subject. |
text | text or html | The plain-text version. |
html | text or html | The HTML version. Send both when you can; with only HTML, the text version is made from it. |
attachments | no | A list of files: filename, content, content_type. The content is base64-encoded. |
template | no | The name of an email connected in Settings → API keys, e.g. welcome. Instead of text and html. |
params | no | With a template: the values for its {{params.…}} tags, e.g. {"first_name": "Aysel"}. Up to 100 values. |
The answer
When the email is sent: status 200 and {"id": "…", "from": "info@yourcompany.com", "to": ["client@example.com"], "recipients": 1, "status": "sent"}. With a template, "template": "welcome" too.
When today's daily limit is used up but tomorrow's still has room: status 202 and the same fields with "status": "queued", "deliverAfter": "2026-10-13T00:00:00Z". The email is accepted and SendHaste keeps it; it goes out at deliverAfter (the next midnight UTC), or as soon after as the mail server takes it. Treat 202 as success and don't send it again: a retry would deliver it twice.
When it isn't: an error status, and {"error": {"code": "…", "message": "…"}}. The code stays the same, so your code can check it; the message says what to fix.
| Status | code | What to do |
|---|---|---|
401 | missing_api_key, invalid_api_key | Check the Authorization header, or make a new key: this one was revoked. |
403 | from_not_allowed | Send from an address on your domains (not catchall@, which only receives), or the domain or the one address the key is limited to. |
403 | api_disabled | Sending through the API isn't switched on for your organization: ask us from the Support page. |
400 | invalid_json | Send a JSON object. |
415 | unsupported_media_type | Set Content-Type: application/json. |
422 | invalid_field, mailbox_not_found | Fix the field the message names, or create the From mailbox first. |
404 | template_not_found | Connect the email name to a template in Settings → API keys, for the From address, its domain or the whole organization, or check its spelling. |
413 | too_large | Send smaller attachments. |
429 | rate_limited, daily_limit | Too many requests: wait the seconds in the Retry-After header. Daily limit: today's and tomorrow's emails are both used up, or the mail server's daily limit for the address is reached; wait the seconds in Retry-After (until midnight UTC) and send it then. |
502, 503 | send_failed, mailbox_not_ready | Not sent: try again in a few minutes. If it goes on, write to us. An email the mail server accepted is never answered with it, even when its answer was slow. |
Limits
- Up to 60 requests a minute per key.
- Up to 50 recipients per email (to, cc and bcc together).
- Up to 20 attachments and 25 MB per email.
- Each domain can send up to 300 emails a day, whether from SendHaste or the API, and each of its mailboxes can email as many people as the domain's limit, or fewer if an Org Super Admin sets People each mailbox may email a day on the domain's page. A newly connected domain starts lower; its page in Settings → Domains shows Emails today against its limit, Refused today, Held for tomorrow, and Warming up while it rises.
- An email over today's limit isn't lost: SendHaste keeps it and sends it after midnight UTC, counted against tomorrow (status
202). If the mail server is still at its own limit then, it goes out as soon as the server takes it. Only when tomorrow's limit is used up too is it refused (daily_limit). - Emails waiting like this are listed under Scheduled in the mailbox's sidebar, under Held by the daily sending limit; there's nothing to do, they go out by themselves.
Prefer SMTP? Many apps and frameworks can send through a mailbox with SMTP instead: see Outlook, Apple Mail and phone apps for the server and port. The same daily limits apply.
Can't find what you need? Send us a message.