Quickstart
Send your first email via the MisarMail API in under 5 minutes
Quickstart
- Create an API key in Settings → API Keys. 2)
POST https://api.misar.io/mail/v1/sendwithAuthorization: Bearer msk_.... 3) Passfrom,to,subject, andhtmlortext. Done.
Prerequisites
send scope (Settings → API Keys)Step 1: Create an API Key
Click New API Key, name it, and select the send scope.
Copy the full key (starts with msk_). It won't be shown again.
Store your API key securely. Never commit it to source control.
Step 2: Send Your First Email
curl https://api.misar.io/mail/v1/send \
-H "Authorization: Bearer msk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "[email protected]", "name": "You" },
"to": [{ "email": "[email protected]", "name": "Recipient" }],
"subject": "Hello from MisarMail",
"html": "<h1>It works!</h1><p>Your first email via MisarMail API.</p>",
"text": "It works! Your first email via MisarMail API."
}'
const response = await fetch("https://api.misar.io/mail/v1/send", {
method: "POST",
headers: {
"Authorization": "Bearer msk_your_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
from: { email: "[email protected]", name: "You" },
to: [{ email: "[email protected]", name: "Recipient" }],
subject: "Hello from MisarMail",
html: "<h1>It works!</h1><p>Your first email via MisarMail API.</p>",
text: "It works! Your first email via MisarMail API.",
}),
});
const data = await response.json();
console.log(data);
// { success: true, message_id: "...", provider: "..." }
import requests
response = requests.post(
"https://api.misar.io/mail/v1/send",
headers={
"Authorization": "Bearer msk_your_key_here",
"Content-Type": "application/json",
},
json={
"from": {"email": "[email protected]", "name": "You"},
"to": [{"email": "[email protected]", "name": "Recipient"}],
"subject": "Hello from MisarMail",
"html": "<h1>It works!</h1><p>Your first email via MisarMail API.</p>",
"text": "It works! Your first email via MisarMail API.",
},
)
print(response.json())
# {"success": True, "message_id": "...", "provider": "..."}
Step 3: Understand the Response
A successful send returns:
{
"success": true,
"message_id": "<[email protected]>",
"provider": "smtp-pool-name"
}
A queued response (provider temporarily unavailable — will auto-retry):
{
"success": false,
"queued": true,
"message": "Email queued for retry"
}
A suppressed response (recipient previously unsubscribed or bounced):
{
"success": false,
"suppressed": true,
"error": "Send suppressed — recipient unsubscribed or bounced"
}
A 202 Accepted with queued: true is not an error. The email will be delivered automatically. Do not retry.
A 422 Unprocessable Entity with suppressed: true means the recipient is on your suppression list (unsubscribed or hard-bounced). This is expected and should not be retried.
Sandbox Mode
Use sandbox mode during development to test your integration without sending real emails. Sandbox sends are stored in the sandbox_sends table and never delivered to recipients.
Add the X-MisarMail-Sandbox: true header to any send request:
curl https://api.misar.io/mail/v1/send \
-H "Authorization: Bearer msk_your_key_here" \
-H "Content-Type: application/json" \
-H "X-MisarMail-Sandbox: true" \
-d '{
"from": { "email": "[email protected]" },
"to": [{ "email": "[email protected]" }],
"subject": "Test",
"text": "Sandbox test — not delivered."
}'
Sandbox responses look identical to real sends but the provider field will be "sandbox".
Sandbox sends count against your rate limits but not against your plan's monthly send quota.
Environment Variables
Use environment variables to keep your key out of source code:
MISARMAIL_API_KEY=msk_your_key_here
const response = await fetch("https://api.misar.io/mail/v1/send", {
headers: {
Authorization: `Bearer ${process.env.MISARMAIL_API_KEY}`,
},
// ...
});
import os
import requests
headers = {
"Authorization": f"Bearer {os.environ['MISARMAIL_API_KEY']}",
}