Developers

Everything you need to integrate

Connection settings, limits, SMTP replies and webhook verification, on one page.

Connection

SMTP settings

Host: smtp.mailerace.com
Port 587: STARTTLS (recommended)
Port 465: Implicit TLS (SMTPS)
Authentication: PLAIN or LOGIN, over TLS only
Username / password: An SMTP credential from your dashboard
From address: Any address at a verified domain
Max message size: 10 MB (Free) · 25 MB (paid)

Guides

Integration guides

Step-by-step setup for popular frameworks and platforms.

Replies

SMTP responses you may see

Every refusal comes with a standard SMTP code and a plain-language reason. 4xx codes are temporary and retried by your client; 5xx codes are permanent.

SMTP response codes
Reply	What it means
550 5.7.1 Sender domain not verified	The envelope sender is not at a domain verified in this workspace, or the credential is not allowed to use it.
550 5.7.1 Account in sandbox mode	Until your account is approved you can only send to your own verified domains and team members.
550 5.1.1 Recipient suppressed	The address hard-bounced or complained before. Remove it, or delete the suppression if you are sure.
452 4.5.3 Too many recipients	The message exceeds your plan’s recipients per message. Split it.
451 4.7.1 Rate limit exceeded	You are sending faster than your plan or credential allows. Your client will retry automatically.
452 4.2.2 Sending quota exceeded	The daily or monthly allowance is used up (Free plan) or a hard cap applies.
552 5.3.4 Message too large	The message with attachments exceeds the plan’s size limit.
451 4.3.0 Temporary failure	Something on our side is unavailable. Nothing is lost: retry later (clients do this automatically).

Webhooks

Verify signed webhooks

Every event is a JSON POST with an X-Webhook-Signature header: a timestamp and an HMAC-SHA256 of `timestamp.body` using your endpoint secret. Reject requests older than five minutes.

domain.verifieddomain.verification_failedmessage.* events: coming soon

import { createHmac, timingSafeEqual } from 'node:crypto';

// header: X-Webhook-Signature: t=1731654000,v1=5f2c…
export function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // 5-minute tolerance
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return header.split(',').filter((p) => p.startsWith('v1=')).some((p) => {
    const sig = Buffer.from(p.slice(3), 'hex');
    return sig.length === 32 && timingSafeEqual(sig, Buffer.from(expected, 'hex'));
  });
}

FAQ

Developer questions

Is there an HTTP API?

An HTTP sending API is coming soon. SMTP works today with every language; your code will not need to change when the API arrives.

Why are there two v1 signatures in a webhook header?

While you rotate a webhook secret, events are signed with both the new and the previous secret, so your endpoint keeps verifying during the switch. Accept the request if any v1 value matches.

How are webhooks retried?

Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours and twice after 10 hours. You can also resend any event from the dashboard.

Build with MailerAce

Standard protocols, clear errors and signed events. Nothing proprietary to learn.

Get early access View pricing