Send email

POST https://sendhawk.online/api/emails

Sends one email. The request returns once Amazon SES has accepted the message, with the id you use to retrieve it and to match webhook events.

Headers

Body

Send either templateId (with optional variables), or subject together with html, text or both. A request with both kinds of content, or with neither, answers 400.

Amazon SES delivers at most 50 recipients per message across to, cc and bcc together, so keep the total at 50 or fewer. Every recipient sees the to and cc addresses; to send the same content to people who should not see each other, send one email per recipient.

Response

200 OK with the id of the email:

{
  "id": "4f1c2b8e-7a3d-4e5f-9b21-0c6d8e9f1a2b"
}

Examples

curl https://sendhawk.online/api/emails \
  -H "Authorization: Bearer $SENDHAWK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt" \
  -d '{
    "from": "Acme <billing@yourdomain.com>",
    "to": ["ada@example.com"],
    "bcc": "archive@yourdomain.com",
    "replyTo": "support@yourdomain.com",
    "subject": "Your receipt for order 1042",
    "html": "<h1>Thanks, Ada</h1><p>We received your payment of EUR 49.00.</p>",
    "text": "Thanks, Ada. We received your payment of EUR 49.00."
  }'

curl https://sendhawk.online/api/emails \
  -H "Authorization: Bearer $SENDHAWK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "ada@example.com",
    "templateId": "0193a4f2-5c1e-7b8d-9e0f-1a2b3c4d5e6f",
    "variables": { "name": "Ada", "code": "428913" }
  }'

Idempotency

Networks fail after a request has been sent, and a blind retry can then send the same email twice. Send an Idempotency-Key header to make the retry safe: when the same key arrives again within 24 hours, SendHawk.Online returns the original response instead of sending again.

• Use a value that identifies the email in your own system, such as order-1042-receipt or a UUID you store with the job.
• Use a new key for every distinct email. A key that is reused within 24 hours never sends a second email.
• Retry 429 and 5xx responses with the same key. See Errors and limits.

What happens next

The email starts in the sent status, which means Amazon SES accepted it. From there it moves to delivered, bounced or complained as the receiving server reports back, and to opened and clicked when tracking is on for the domain. Retrieve email shows the current status; webhooks push each change to you.

A recipient on your suppression list is never sent to: the request answers 422 instead.

Errors

Every error uses the same error format.