neuMails API

Send transactional emails at scale — via HTTP API or SMTP. Built-in tracking, automatic bounce suppression, per-recipient event logging, metadata passthrough, and real-time webhooks.

Quick Start

Choose your preferred integration method. Both share the same credentials, tracking, and deliverability features.

API Base URL: https://api.neumails.com
SMTP Server: smtp.neumails.com · Port 587 · STARTTLS · TLS 1.2+ required

Authentication

Your credentials are generated in the neuMails portal when you add a sending domain. A single credential pair works for both HTTP API and SMTP.

Quotas

Each account has a credit pool that decrements in real time with every email sent. When the pool reaches zero, further sends are rejected until credits are added.

Send Email — HTTP API

POST/send

https://api.neumails.com/send

Request Parameters

* At least one of html or text is required. Send both for best deliverability.

Request Limits

Example — Single Recipient (cURL)

curl -X POST https://api.neumails.com/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "nm_yourcompany_abc123def456",
    "api_secret": "YOUR_API_SECRET",
    "from": "orders@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Order Confirmation #12345",
    "html": "<h1>Thank you for your order!</h1>"
  }'

Success Response

// HTTP 200
{
  "success": true,
  "message_id": "a3f8b2c17d4e",
  "recipients": 3
}

Multiple Recipients

Both HTTP API and SMTP support sending to multiple recipients in a single request. Each recipient is tracked, logged, and suppression-checked independently.

HTTP API — Multiple Recipients

Pass a comma-separated list of email addresses in the to field.

curl -X POST https://api.neumails.com/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "nm_yourcompany_abc123def456",
    "api_secret": "YOUR_API_SECRET",
    "from": "team@yourdomain.com",
    "to": "alice@example.com, bob@example.com, carol@example.com",
    "subject": "Team Update",
    "html": "<h1>Hello Team</h1>"
  }'

SMTP — Multiple Recipients

Issue a separate RCPT TO command for each recipient, or pass a comma-separated list in the To header. neuMails logs each recipient individually.

// Node.js — Nodemailer
await transporter.sendMail({
  from: 'team@yourdomain.com',
  to: 'alice@example.com, bob@example.com, carol@example.com',
  subject: 'Team Update',
  html: '<h1>Hello Team</h1>'
});

CC & BCC NEW in v3.2

The HTTP API now supports standard carbon-copy and blind-carbon-copy semantics.

curl -X POST https://api.neumails.com/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "nm_yourcompany_abc123def456",
    "api_secret": "YOUR_API_SECRET",
    "from": "billing@yourdomain.com",
    "to": "customer@example.com",
    "cc": "accounts@example.com",
    "bcc": "audit@yourdomain.com",
    "subject": "Invoice #9001",
    "html": "<p>Invoice attached.</p>"
  }'

Metadata Passthrough NEW in v3.2

Attach your own identifiers — order IDs, customer IDs, campaign tags — to any message. neuMails stores the object and echoes it back inside every webhook event generated by that message (injection, delivery, bounce, deferred, open, click), so you never need to maintain your own message_id lookup table.

Rules

Example — Send with Metadata

curl -X POST https://api.neumails.com/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "nm_yourcompany_abc123def456",
    "api_secret": "YOUR_API_SECRET",
    "from": "orders@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Order Confirmation #12345",
    "html": "<h1>Thank you!</h1>",
    "metadata": {
      "order_id": "ORD-12345",
      "customer_id": "CUST-8871",
      "campaign": "order-confirmation"
    }
  }'

Example — Webhook Event with Metadata Echoed

{
  "event": "delivery",
  "event_id": "mm3b2983c14e07ea",
  "message_id": "a3f8b2c17d4e",
  "email": "customer@example.com",
  "subject": "Order Confirmation #12345",
  "dsn_status": "2.0.0",
  "timestamp": "2026-07-10T11:42:07.000Z",
  "metadata": {
    "order_id": "ORD-12345",
    "customer_id": "CUST-8871",
    "campaign": "order-confirmation"
  }
}

Error Handling

Suppression Error — Example

// HTTP 422 — all recipients suppressed
{
  "error": "All recipients are suppressed",
  "message": "All recipients have previously hard-bounced. Release from suppression list to send again."
}

SMTP Relay

SMTPsmtp.neumails.com:587

Use neuMails as your SMTP relay — compatible with any application, language, or email client. All emails sent via SMTP receive automatic open tracking, click tracking, bounce suppression, and per-recipient event logging.

Connection Settings

TLS Requirements & Port Guide

neuMails SMTP requires TLS 1.2 or higher. TLS 1.0 and TLS 1.1 are not supported. Two ports are available depending on your application's SSL mode.

.NET Framework Fix

Old .NET Framework (4.5 and below) defaults to TLS 1.0. Add this line before creating your SmtpClient:

// Add BEFORE SmtpClient initialization
System.Net.ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

// Port 587 — STARTTLS (recommended)
SmtpClient client = new SmtpClient("smtp.neumails.com", 587);
client.EnableSsl = false;  // IMPORTANT — false for port 587
client.UseDefaultCredentials = false;
client.Credentials = new NetworkCredential("nm_yourcompany_xxx", "YOUR_SECRET");
client.DeliveryMethod = SmtpDeliveryMethod.Network;

// Port 465 — SMTPS (if your app requires EnableSsl = true)
// SmtpClient client = new SmtpClient("smtp.neumails.com", 465);
// client.EnableSsl = true;

TLS Compatibility by Platform

SMTP — Code Examples

Python

# Python 3.x
import smtplib, ssl
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart

msg = MIMEMultipart('alternative')
msg['From'] = 'orders@yourdomain.com'
msg['To'] = 'customer@example.com'
msg['Subject'] = 'Order Confirmation'
msg.attach(MIMEText('<h1>Thank you!</h1>', 'html'))

context = ssl.create_default_context()
with smtplib.SMTP('smtp.neumails.com', 587) as server:
    server.starttls(context=context)
    server.login('nm_yourcompany_abc123def456', 'YOUR_API_SECRET')
    server.send_message(msg)

Node.js

// Nodemailer
const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: 'smtp.neumails.com',
  port: 587,
  secure: false,  // false = STARTTLS on port 587
  auth: {
    user: 'nm_yourcompany_abc123def456',
    pass: 'YOUR_API_SECRET'
  }
});

await transporter.sendMail({
  from: 'orders@yourdomain.com',
  to: 'customer@example.com',
  subject: 'Order Confirmation',
  html: '<h1>Thank you!</h1>'
});

PHP (PHPMailer)

// PHPMailer
$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host       = 'smtp.neumails.com';
$mail->SMTPAuth   = true;
$mail->Username   = 'nm_yourcompany_abc123def456';
$mail->Password   = 'YOUR_API_SECRET';
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->Port       = 587;

$mail->setFrom('orders@yourdomain.com');
$mail->addAddress('customer@example.com');
$mail->isHTML(true);
$mail->Subject = 'Order Confirmation';
$mail->Body    = '<h1>Thank you!</h1>';
$mail->send();

.NET (C#)

// .NET — correct configuration for neuMails (port 465, EnableSsl = true)
System.Net.ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

SmtpClient client = new SmtpClient("smtp.neumails.com", 465);
client.EnableSsl = true;
client.UseDefaultCredentials = false;
client.Credentials = new NetworkCredential(
    "nm_yourcompany_abc123def456",
    "YOUR_API_SECRET"
);
client.DeliveryMethod = SmtpDeliveryMethod.Network;

MailMessage mail = new MailMessage();
mail.From = new MailAddress("orders@yourdomain.com");
mail.To.Add("customer@example.com");
mail.Subject = "Order Confirmation";
mail.Body = "<h1>Thank you!</h1>";
mail.IsBodyHtml = true;
client.Send(mail);

Java

// Jakarta Mail
Properties props = new Properties();
props.put("mail.smtp.host", "smtp.neumails.com");
props.put("mail.smtp.port", "587");
props.put("mail.smtp.auth", "true");
props.put("mail.smtp.starttls.enable", "true");
props.put("mail.smtp.ssl.protocols", "TLSv1.2");

Session session = Session.getInstance(props, new Authenticator() {
    protected PasswordAuthentication getPasswordAuthentication() {
        return new PasswordAuthentication(
            "nm_yourcompany_abc123def456", "YOUR_API_SECRET");
    }
});

Message msg = new MimeMessage(session);
msg.setFrom(new InternetAddress("orders@yourdomain.com"));
msg.setRecipients(Message.RecipientType.TO, InternetAddress.parse("customer@example.com"));
msg.setSubject("Order Confirmation");
msg.setContent("<h1>Thank you!</h1>", "text/html");
Transport.send(msg);

Ruby

# Net::SMTP with TLS 1.2
require 'net/smtp'

message = <<~MSG
From: orders@yourdomain.com
To: customer@example.com
Subject: Order Confirmation
Content-Type: text/html

<h1>Thank you!</h1>
MSG

smtp = Net::SMTP.new('smtp.neumails.com', 587)
smtp.enable_starttls
smtp.start('yourdomain.com', 'nm_yourcompany_abc123def456',
           'YOUR_API_SECRET', :login) do |s|
  s.send_message(message, 'orders@yourdomain.com', 'customer@example.com')
end

Attachments

Both HTTP API and SMTP support file attachments. Maximum total size is 30 MB per email with up to 10 attachments.

Allowed File Types

HTTP API — Attachment Example

curl -X POST https://api.neumails.com/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "nm_yourcompany_abc123def456",
    "api_secret": "YOUR_API_SECRET",
    "from": "billing@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Invoice #12345",
    "html": "<p>Please find your invoice attached.</p>",
    "attachments": [
      {
        "filename": "invoice_12345.pdf",
        "content": "JVBERi0xLjQ...(base64 encoded content)...",
        "content_type": "application/pdf"
      }
    ]
  }'

Open Tracking

A transparent 1×1 tracking pixel is automatically injected into every HTML email. When the recipient opens the email and images load, an open event is recorded and sent to your webhook.

Open events include the recipient's IP address and user agent. Opens are attributed per-recipient — including individual CC and BCC recipients. Some email clients preload images through proxies, which may result in multiple open events per email — this is expected behavior.

Click Tracking

All https:// links in your HTML body are automatically rewritten to tracking URLs. When a recipient clicks, the event is recorded and they are instantly redirected (HTTP 302) to the original destination.

Click events include the original target URL, recipient's IP address, and user agent. Each unique link in a message gets a separate tracking ID, and clicks are attributed to the individual recipient who clicked.

Suppression List

When an email hard-bounces, the recipient address is automatically added to your suppression list. Future sends to that address are blocked before delivery, protecting your sender reputation.

What Gets Suppressed

Managing Suppressions

From the neuMails portal you can view all suppressed addresses with bounce reason and date, release individual or multiple addresses, manually add addresses, and export the full list as CSV.

Pre-Send Behaviour

DKIM Key Management

neuMails supports both 1024-bit and 2048-bit RSA DKIM keys. You can select your preferred key size from the API Key Details page in the portal and regenerate at any time.

Choosing a Key Size

How to Regenerate

Go to Portal → API Keys → View Domain → DKIM Record. Select the desired key size from the dropdown and click Regenerate DKIM. The new key is deployed to the sending infrastructure automatically.

Delivery & Retry Policy

When an email cannot be delivered immediately due to a temporary failure (4xx response from the receiving mail server), neuMails automatically retries delivery with a gradually increasing interval. Permanent failures (5xx) are bounced immediately without retrying.

How Retries Work

Webhook Events

neuMails sends real-time event notifications to your webhook URL as HTTP POST requests with a JSON payload. Configure your webhook URL and event subscriptions in the portal under domain settings.

Webhook Headers

Example Payload — Delivery Event

{
  "event": "delivery",
  "event_id": "mm3b2983c14e07ea",
  "message_id": "a3f8b2c17d4e",
  "email": "customer@example.com",
  "from": "orders@yourdomain.com",
  "subject": "Order Confirmation #12345",
  "dsn_status": "2.0.0",
  "source_ip": "x.x.x.x",
  "timestamp": "2026-07-10T11:42:07.000Z",
  "metadata": { "order_id": "ORD-12345" }
}

Example Payload — Suppression Event NEW

{
  "event": "suppression",
  "event_id": "mm3b2983c14e07ec",
  "message_id": "a3f8b2c17d4e",
  "email": "bounced-user@example.com",
  "from": "orders@yourdomain.com",
  "subject": "Order Confirmation #12345",
  "suppression_reason": "hard_bounce",
  "suppression_source": "bounce",
  "timestamp": "2026-07-10T11:42:05.000Z"
}

Example Payload — Deferred Event NEW

{
  "event": "deferred",
  "event_id": "mm3b2983c14e07ed",
  "message_id": "a3f8b2c17d4e",
  "email": "customer@example.com",
  "from": "orders@yourdomain.com",
  "subject": "Order Confirmation #12345",
  "dsn_status": "4.7.0",
  "dsn_diag": "451 4.7.0 Try again later",
  "timestamp": "2026-07-10T11:45:12.000Z"
}

Example Payload — Bounce Event

{
  "event": "bounce",
  "event_id": "mm3b2983c14e07eb",
  "message_id": "a3f8b2c17d4e",
  "email": "bounced-user@example.com",
  "bounce_type": "hard",
  "bounce_category": "bad-mailbox",
  "dsn_status": "5.1.1",
  "dsn_diag": "550 5.1.1 User unknown",
  "timestamp": "2026-07-10T11:43:02.000Z"
}

Example Payload — Click Event

{
  "event": "click",
  "event_id": "mm3b2983c14e07ee",
  "message_id": "a3f8b2c17d4e",
  "email": "customer@example.com",
  "subject": "Order Confirmation #12345",
  "link_url": "https://yourdomain.com/order/12345",
  "timestamp": "2026-07-10T12:01:59.000Z",
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0..."
}

Webhook Verification

Every webhook includes an X-NM-Signature header — an HMAC-SHA256 hex digest of the raw JSON body, signed with your webhook secret.

// Node.js verification
const crypto = require('crypto');
const expected = crypto
  .createHmac('sha256', YOUR_WEBHOOK_SECRET)
  .update(rawRequestBody)
  .digest('hex');

if (expected === req.headers['x-nm-signature']) {
  // Verified — process event
}

# Python verification
import hmac, hashlib

expected = hmac.new(
    WEBHOOK_SECRET.encode(), raw_body, hashlib.sha256
).hexdigest()

if hmac.compare_digest(expected, request.headers['X-NM-Signature']):
    # Verified

DNS Records

Before sending, verify your domain by adding these DNS records. The neuMails portal provides the exact values for your domain under API Keys → View Domain.

SPF

If you already have an SPF record, merge it by adding include:neumails.com before the ~all or -all. Do not create a second SPF record.

DKIM

DMARC

Response Codes

HTTP API

SMTP

Changelog

v3.2 — July 10, 2026

v3.1 — April 27, 2026

v3.0 — March 25, 2026

v2.0 — February 26, 2026

v1.5 — February 20, 2026

v1.0 — February 10, 2026