SMTP Submission

In addition to the REST API, Altermail provides a standard SMTP submission server. Use it to send email directly from your application, migrate from another ESP without code changes, or use any SMTP-compatible library (Nodemailer, PHPMailer, Python's smtplib, etc.).

Using WordPress?

No plugin or theme code required. Install an SMTP plugin — WP Mail SMTP, Post SMTP, Easy WP SMTP, and FluentSMTP all work — and enter the connection settings below into its “Other SMTP” setup screen: host, port 2525, STARTTLS, then your domain (or apikey) as the username and your API key as the password. wp_mail() calls from any plugin or theme, including WooCommerce order emails and contact forms, route through Altermail automatically from that point on.

Connection settings

Hostsmtp.altermail-console.com.ng
Port2525
EncryptionSTARTTLS (required in production)
UsernameYour verified sender domain (e.g. yourdomain.com) or the literal string apikey
PasswordYour Altermail API key

Username: domain vs apikey

The SMTP username controls whether domain ownership is verified at connection time:

  • •Username = your domain (e.g. yourdomain.com): Altermail verifies during AUTH that this domain is a verified sender on your account. The MAIL FROM address must also use this domain; any mismatch is rejected immediately. DKIM signing is loaded for the session if the domain has an active DKIM key.
  • •Username = apikey (literal string): No domain is pre-checked at AUTH. You can use any verified domain in MAIL FROM, and domain ownership is verified at send time. DKIM signing is not loaded for the session.

Using your domain as the username is recommended: it loads DKIM signing for the session and enforces sender domain ownership at AUTH rather than at relay time.

DKIM signing

When you use your domain as the SMTP username and that domain has an active DKIM key set up in the Domains page, your outgoing messages are automatically signed with RSA-SHA256. No extra parameters are needed; signing happens server-side, exactly the same as the REST API.

If DKIM signing fails for any reason (e.g. a key format issue), the message is still delivered unsigned. Signing is non-fatal and will never cause a delivery failure.

Quota & billing

SMTP sends consume quota from the same pool as REST API sends; they are not separate. Quota is deducted before the message is relayed to the mail server. Each recipient address counts as one credit, identical to the API.

!If your quota is exhausted, the server returns 452 4.2.1 and the message is not sent. Your SMTP client will surface this as a send error. Buy a PAYG bundle or upgrade your plan from the Billing page.

Delivery event tracking

Every message accepted via SMTP is tracked in the same delivery events pipeline as the REST API. When the server accepts your message (250 OK), it returns an Altermail-assigned messageId in the response text:

250 OK messageId=5a4911ad-9cdb-4cb4-bf74-a317927cd344

With Nodemailer, read it from info.response. Store this value to look up events later via GET /v1/user/email/events?messageId=.... Bounce and delivery webhooks reference the same id.

Rate limits by plan

Three separate limits apply per account. All three scale with your plan.

PlanConcurrent connectionsMessages per sessionSends per minute
Free21010/min
Developer55030/min
Growth1010060/min
Business25250120/min
Enterprise50500300/min

Exceeding concurrent connections returns 421 4.4.5. Hitting the messages-per-session cap returns 421 4.4.3 and requires a reconnect. Sending too fast returns 421 4.4.5 and clears after 60 seconds.

Other limitations

  • •50 recipients per message: The total number of To + CC + BCC addresses per message. Exceeded recipients are rejected with 452 4.5.3 before DATA is processed.
  • •25 MB message size: The maximum raw message size including headers, body, and attachments. Oversized messages are rejected with 552 5.3.4.
  • •Concurrent connection limit: The number of simultaneous open SMTP connections your account can hold depends on your plan (2 on Free, up to 50 on Enterprise). Exceeding this returns 421 4.4.5.
  • •Messages per session: Each connection can send a limited number of messages before you must reconnect (10 on Free, up to 500 on Enterprise). This is standard SMTP behaviour shared by all major providers.
  • •Per-minute send rate: Throughput is capped per minute by your plan (10/min on Free, up to 300/min on Enterprise), matching the same tiers as the REST API rate limit. Only successfully relayed messages count toward the window.
  • •STARTTLS required in production: The server advertises STARTTLS. If TLS certificates are loaded, plaintext AUTH is not allowed. Always configure your client to use STARTTLS.
  • •Delivery events tracked per primary recipient only: The messageId is logged against the first To: address. Bounce and delivery tracking works the same as the API. The assigned messageId is returned in the 250 response so you can correlate events later.
  • •Unsubscribe suppression and email category: Add an X-Altermail-Category header set to "transactional" or "marketing" before sending. Transactional emails (OTPs, receipts, account alerts) are always delivered regardless of unsubscribe status. Marketing emails are blocked for recipients who have unsubscribed, quota is still deducted, and a soft bounce event is recorded. If the header is omitted, Altermail auto-detects the category from the Subject line.

SMTP error codes

These are the standard SMTP responses your client will receive when something goes wrong. 4xx codes are transient (retry later); 5xx codes are permanent (fix the issue first).

CodeMeaningFix
535 5.7.8AUTH failedWrong API key, suspended account, or unverified domain.
421 4.4.5Too many connectionsYour account has reached its concurrent connection limit. Close an existing connection first.
530 5.7.0Auth requiredMAIL FROM issued without prior AUTH.
553 5.1.3Sender domain mismatchMAIL FROM domain differs from the domain used as username.
421 4.4.3Message limit reachedYour account hit its messages-per-session limit. Reconnect to continue sending.
452 4.5.3Too many recipientsMore than 50 RCPT TO addresses in one message.
552 5.3.4Message too largeRaw message exceeds the 25 MB limit.
421 4.4.5Sending too fastPer-minute send rate exceeded for your plan. Slow down and retry.
452 4.2.1Quota exceededMonthly or daily email limit reached, or no PAYG credits remaining.
421 4.4.1Relay failureTransient error relaying to the mail server, retry later.

Code examples

Replace YOUR_API_KEY with your API key from the Overview page and yourdomain.com with a verified sender domain.

# curl supports SMTP natively, useful for quick testing
curl smtp://smtp.altermail-console.com.ng:2525 \
  --ssl-reqd \
  --user "yourdomain.com:YOUR_API_KEY" \
  --mail-from "hello@yourdomain.com" \
  --mail-rcpt "recipient@example.com" \
  --upload-file - << 'EOF'
From: hello@yourdomain.com
To: recipient@example.com
Subject: Hello from Altermail SMTP
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8

Hello! This is a test email sent over SMTP.
EOF

SMTP vs REST API: which should I use?

REST APISMTP
Ease of useSimple HTTP call from any languageRequires SMTP library / config
TemplatesSupported (active template used automatically)Not supported, send raw MIME
AttachmentsBase64 in JSON bodyNative MIME, use your library's attachment API
DKIM signingAutomaticAutomatic when domain is the username
Delivery eventsFull tracking + webhooksFull tracking + webhooks
Migration from another ESPRequires code changesChange host/port/credentials only
Rate limit60 sends/min per tokenPer-minute cap by plan (10/min Free, up to 300/min Enterprise)
Best forNew integrations, programmatic sendsESP migrations, SMTP-native frameworks