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.

RequestWhat it does
POST https://sendhaste.com/api/v1/emailsSends one email: your own content, or one of your templates with values.
GET https://sendhaste.com/api/v1/templatesLists the emails connected to templates, and the values each one uses.
GET https://sendhaste.com/api/v1/sendersLists the addresses the key may send from.
GET https://sendhaste.com/api/v1/openapi.jsonThe whole API as an OpenAPI 3.1 file, for Postman, code generators and other developer tools. No key needed.

1. Make an API key

  1. An Org Super Admin opens Settings → API keys.
  2. 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.
  3. 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
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."
  }'
JavaScript (Node.js 18+)
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.

  1. 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.
  2. 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.
  3. Under Send a test, send it to yourself with some values to see how it looks.
  4. Your website sends template with the name, and params with the values. The template's subject is used, unless you send a subject.
curl
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 from params when 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

  1. Make a template called Welcome, with the subject Welcome, {{params.first_name|there}}!, a heading Hi {{params.first_name|there}} and a button to {{params.verify_url}}.
  2. Connect it as welcome in Settings → API keys, and make a key that sends from your address.
  3. Put the key in your website's settings (for example an environment variable SENDHASTE_API_KEY).
  4. Where your website saves a new user, send the request. Pick your language:
JavaScript (Node.js 18+)
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 },
  }),
});
PHP
$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);
Python
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:

JSON
{"data": [{"name": "welcome", "template_name": "Welcome", "subject": "Welcome, {{params.first_name|there}}!", "params": ["first_name", "verify_url"], "updated_at": "…", "scope": "domain", "for": "yourshop.com"}]}
FieldWhat it is
nameWhat to send as template.
template_nameThe template's name in SendHaste.
subjectThe template's subject, with its tags not yet filled in.
paramsThe {{params.…}} names the template uses: send these in params.
updated_atWhen the template was last changed.
scopeWho it's connected for: organization (every address on your domains), domain or address.
forThe 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.

JSON
{"data": [{"address": "info@yourcompany.com"}, {"address": "noreply@yourcompany.com"}], "domains": [{"domain": "yourcompany.com"}]}
FieldWhat it is
dataEvery 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.
domainsThe 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

FieldRequiredWhat it is
fromyesOne of your addresses, with a name if you like: Your Company <info@yourcompany.com>. It must have a mailbox in SendHaste.
toyesAn address, or a list of addresses.
cc, bccnoAn address, or a list. Bcc recipients aren't shown to the others.
reply_tonoWhere replies go, if not to the From address.
subjectyes, unless templateThe subject line. With a template, it replaces the template's subject.
texttext or htmlThe plain-text version.
htmltext or htmlThe HTML version. Send both when you can; with only HTML, the text version is made from it.
attachmentsnoA list of files: filename, content, content_type. The content is base64-encoded.
templatenoThe name of an email connected in Settings → API keys, e.g. welcome. Instead of text and html.
paramsnoWith 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.

StatuscodeWhat to do
401missing_api_key, invalid_api_keyCheck the Authorization header, or make a new key: this one was revoked.
403from_not_allowedSend from an address on your domains (not catchall@, which only receives), or the domain or the one address the key is limited to.
403api_disabledSending through the API isn't switched on for your organization: ask us from the Support page.
400invalid_jsonSend a JSON object.
415unsupported_media_typeSet Content-Type: application/json.
422invalid_field, mailbox_not_foundFix the field the message names, or create the From mailbox first.
404template_not_foundConnect the email name to a template in Settings → API keys, for the From address, its domain or the whole organization, or check its spelling.
413too_largeSend smaller attachments.
429rate_limited, daily_limitToo 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, 503send_failed, mailbox_not_readyNot 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.