Send a receipt from your own code

If your shop, your portal or your own script needs to send somebody a single email — an order confirmation, a shipping update, an invoice, a "your account is ready" note — you can hand it to us and we will send it.

You do not need a flow and you do not need a campaign. One request, one email.

#What you need first

1. A verified sending domain. Reputation → Domains. Without one there is no address to send from and the request is refused with a message saying so.

2. A server key. Settings → General → API keys → Create key. It starts with ae_live_. Keep it on your server.

Never put a server key in a web page. Anything printed in page source can be read by anybody, and a server key can send mail as you.

#Sending one

This is a whole working example. Paste your own key in, change the address, and run it.

Every request with a server key has to be signed — two extra headers, a timestamp and a signature made with your key. The example below does it with openssl. "Connect a custom-built store with the API" explains it, with the same thing in Node.

KEY='PASTE-YOUR-SERVER-KEY-HERE'
BODY='{
  "to":"buyer@yourstore.com",
  "subject":"Your order is on its way",
  "html":"Thanks — order 1044 shipped today. Tracking: 9400 1000 0000 0000",
  "idempotencyKey":"order-1044:shipped"
}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY" \
  | openssl dgst -sha256 -hmac "$KEY" -hex | sed 's/^.* //')
curl -sS https://app.aminoengine.com/api/v1/send \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "X-AE-Timestamp: $TS" \
  -H "X-AE-Signature: sha256=$SIG" \
  --data "$BODY"

The answer is one line:

{ "messageId": "8f2c…", "state": "queued", "deduplicated": false }

messageId is the same id you will see under Messages, with its delivery status beside it. state: "queued" means we have it and it is on its way out — Messages is where you find out whether it was actually delivered.

Three things worth knowing:

1. idempotencyKey stops duplicates. Send the same key twice and the second one comes back with deduplicated: true instead of being sent again. Use something that identifies the event — the order number and what happened to it is ideal. If your script retries after a timeout, nobody gets two copies.

2. You can send a design instead of typing HTML. Swap html for "templateId" and a "variables" object, and we render your design with your branding and fill in the blanks. The id is in the address bar of that design's page.

3. You can send up to fifty at once by posting {"messages": [ ... ]}. A batch always answers 200 with a result for each one, so a single bad address never stops the other forty-nine, and your script never retries forty-nine emails to fix one.

#What we do with it

It goes out on the receipts side of the system, which means it is not held back by somebody's marketing unsubscribe, does not need consent, does not count towards your sending limit and carries no unsubscribe footer. See "Receipts and marketing are two different things" for what that does and does not cover.

#If it didn't work

• 401 saying the key is "missing, malformed, revoked, or does not exist". Usually the request was not signed, the signature is wrong, or your server's clock is more than five minutes out — see "Connect a custom-built store with the API". If all of that is right, make a new key under Settings → General → API keys.
• 403. You used a public key. Those can only report page views and orders, never send mail. Use a server key.
• 422 saying the From address is not verified. The reply lists the domains you have verified. Send from one of those, or finish the DNS steps on the one you wanted.
• 429. You are going too fast, or your new sending domain has hit today's warm-up limit. The reply tells you how many seconds to wait. A brand-new domain has a small daily allowance on purpose — mailbox providers judge a domain that suddenly sends thousands of emails as spam, permanently.
• 405 when you open the address in a browser. That is only a browser asking for a page. Sending is a POST with a key.
• It says it sent and nobody got it. Open Messages and find the id you got back. The row says whether it was delivered, bounced or held back, and why.