NitroMail API

NitroMail sends transactional emails (verification codes, password resets, receipts, notifications) from your own verified domain. You can send with the HTTP API or with SMTP; both go through the same checks and the same pricing. Marketing and bulk emails are not allowed.

Before you send, in the NitroMail panel: confirm your account email, add and verify your domain (DNS), create a sending address, and create an API key or SMTP credentials. Each sent email is charged from your balance; you only pay for what you send.

Authentication

Send your API key in the Authorization header of every request. Create keys under API Keys in the panel; a key is shown only once. Never put an API key in browser or mobile app code.

Authorization: Bearer nm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Send an email

POST https://api.nitromail.io/v1/messages with a JSON body.

curl https://api.nitromail.io/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "from_name": "Your Shop",
    "to": "[email protected]",
    "subject": "Your order #1234",
    "html": "<p>Thanks for your order!</p>",
    "text": "Thanks for your order!"
  }'

Request fields

Field	Required	Description
`from`	yes	One of your active sending addresses on a verified domain.
`from_name`	no	Display name of the sender (max 200 characters).
`to`	yes	A recipient as `"[email protected]"` or `{"email": "[email protected]", "name": "Ann"}`, or a list of up to 50 of them. Every recipient receives a separate email and is charged separately.
`reply_to`	no	Reply-To address.
`subject`	yes	Max 998 characters, no line breaks.
`html`	one of	HTML version.
`text`	one of	Plain-text version. Sending both improves deliverability. Max 1 MB together.
`headers`	no	Up to 10 custom headers: `X-*` headers and `List-Unsubscribe` / `List-Unsubscribe-Post`.

Attachments, cc and bcc are not supported. Need attachments? Please contact support. Tip: link to the file (for example an invoice download page) instead of attaching it.

Response

The response lists every recipient with its own result. charged_usd is the total deducted from your balance for this request.

{
  "success": true,
  "messages": [
    { "to": "[email protected]", "id": "em_3f9c2a1b7d4e5f60a1b2c3d4", "status": "queued" }
  ],
  "charged_usd": "0.002000"
}

queued - accepted and handed to our mail servers.
pending - accepted; it will be sent shortly (automatic retry).
held - accepted but waiting for a content review before sending.
suppressed - not sent and not charged: the recipient bounced or unsubscribed before.
rejected - not sent; see error. Rejected emails are not charged (or are refunded automatically).

Follow every email, its delivery timeline and its cost under Messages and Transactions in the panel.

Errors

When the whole request fails, nothing is sent or charged:

{
  "success": false,
  "error": { "type": "invalid_request", "message": "subject is required.", "field": "subject" }
}

HTTP	type	Meaning
400	`invalid_json`	The body is not a JSON object.
401	`unauthorized`	Missing, wrong or revoked API key.
403	`account_suspended`, `email_not_verified`	The account cannot send.
413	`payload_too_large`	The request or the content is too large.
422	`invalid_request`	A field is invalid; see `field`. Also when no recipient was accepted.
429	`rate_limited`	A sending limit was reached; retry later.
500	`internal_error`	Temporary problem; retry with backoff.

Limits

New accounts start with low limits that grow automatically with a good sending history (low bounce rate, no policy violations): emails per day, emails per minute and new recipients per day (addresses you have never emailed before). The same email to the same recipient is limited to 3 per hour, and any email to one recipient to 20 per hour and 100 per day. Unusual volume is paused for a manual review. Need higher limits? Contact support.

SMTP

Host	`smtp.nitromail.io`
Port 465	SSL/TLS (implicit TLS)
Port 587	STARTTLS (required before login)
Authentication	PLAIN or LOGIN with the SMTP credentials from the panel (not your account password)
Limits	Max 50 recipients and 2 MB per message; no attachments

The From header must be one of your sending addresses. Every envelope recipient (RCPT TO) receives a separate email. Replies:

250 - accepted (queued as em_...).
535 - wrong credentials, suspended account or unconfirmed account email.
451 - temporary (limit reached or server busy); your mail client retries automatically.
550 / 554 - rejected (invalid sender, policy, attachments).

Message statuses

After sending, the status in the panel follows the delivery: queued → delivered, or delayed (temporary, retried), bounced (the recipient server refused it; the address is added to your suppression list), suppressed or canceled. Delivery results do not change the price: an email is charged when it is handed to our mail servers. Keep your bounce rate low: accounts with a high bounce rate are paused.