Skip to content
Mail
Docs

Quickstart

Four steps from a new account to your first email, with plain HTTP.

1. Verify the domain you send from

In the dashboard, under Domains, add the domain your emails come from — acme.ng for receipts@acme.ng — and add the DNS records it shows at your DNS host. You can send from any address at a verified domain.

A new account starts in the sandbox: until we approve it, it sends only to its own members’ confirmed addresses, at most 100 a day. That is enough to try everything below with your own address.

2. Make an API key

Under API keys, make a key. Sending only is all sending needs; a full-access key can also read emails back. The key is shown once: keep it in your app’s secret settings, for example as the environment variable MDH_API_KEY, and never in code you commit.

3. Send

One POST /emails. The Idempotency-Key makes a retry safe: send the same request again with the same key and it is not sent twice (see Idempotency).

curl

curl -X POST https://emails.mydomainshub.com/api/v1/emails \
  -H "Authorization: Bearer $MDH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt" \
  -d '{
    "from": "Acme <receipts@acme.ng>",
    "to": [
      "ada@example.com"
    ],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>"
  }'

Node

// Node 18 or later: fetch is built in.
const response = await fetch('https://emails.mydomainshub.com/api/v1/emails', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MDH_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1042-receipt',
  },
  body: JSON.stringify({
    "from": "Acme <receipts@acme.ng>",
    "to": [
      "ada@example.com"
    ],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>"
  }),
})
const result = await response.json()
if (!response.ok) throw new Error(`${result.name}: ${result.message}`)
console.log(result.id)

Python

# Python 3, standard library only.
import json
import os
import urllib.error
import urllib.request

email = {
    "from": "Acme <receipts@acme.ng>",
    "to": [
        "ada@example.com"
    ],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>"
}

request = urllib.request.Request(
    "https://emails.mydomainshub.com/api/v1/emails",
    method="POST",
    data=json.dumps(email).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['MDH_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "order-1042-receipt",
    },
)
try:
    with urllib.request.urlopen(request) as response:
        print(json.load(response)["id"])
except urllib.error.HTTPError as error:
    problem = json.load(error)
    raise SystemExit(f"{problem['name']}: {problem['message']}")

PHP

<?php
// PHP 7.4 or later, with the curl extension.
$ch = curl_init('https://emails.mydomainshub.com/api/v1/emails');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('MDH_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: order-1042-receipt',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'from' => 'Acme <receipts@acme.ng>',
        'to' => ['ada@example.com'],
        'subject' => 'Your receipt',
        'html' => '<p>Thanks for your order.</p>',
    ]),
]);
$result = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new Exception($result['name'] . ': ' . $result['message']);
}
echo $result['id'];

The answer is the email’s id, with status 200:

{"id":"6f1d3a52-2a0e-4f0b-9d55-0c1f2a3b4c5d"}

It means the email is queued: our sender takes it from there. A refusal is JSON too, with a name and a message that says what to change — see Errors.

4. See what happened

The dashboard’s Emails log shows every email with its status and each event: sent, delivered, bounced and why. Your code can ask too, with a full-access key and the id:

curl https://emails.mydomainshub.com/api/v1/emails/6f1d3a52-2a0e-4f0b-9d55-0c1f2a3b4c5d \
  -H "Authorization: Bearer $MDH_API_KEY"

Next: the API reference, the limits, and scheduling.