Send through SMTP

Some software cannot call an API but can send email through an SMTP server: WordPress, PrestaShop, a CRM, an ERP, an older application of your own. Point it at Azimea’s SMTP relay and its emails go out from your domain, through the same queue, checks and reports as POST /sending/emails. Nothing needs to be installed and no code needs to change.

The relay is for transactional email: order confirmations, password links, invoices, notifications. Newsletters and offers belong in campaigns and flows, which check each person’s consent.

Before you start

1. A verified sending domain. The From: address of every message must be on a domain you have verified in Settings › Sending domains. A message from any other address is refused with 550 5.7.1 (see answers).
2. An API key with the emails:send permission, made in Settings › API keys. It is the SMTP password. The same page shows the settings below and offers to make the key. A key made in a sandbox works too: its emails land in the sandbox’s inbox and reach nobody.

SMTP settings

Setting	Value
Server (host)	smtp.azimea.com
Port and encryption	587 with STARTTLS (recommended). Also 465 with SSL/TLS, or 2525 with STARTTLS if your host blocks 587.
Authentication	On: PLAIN or LOGIN, offered only once the connection is encrypted
Username	azimea (not checked: the key alone identifies your company)
Password	Your API key, azm_live_… (or azm_test_… for a sandbox)
From address	An address on one of your verified domains

Revoking the key in the dashboard stops it for SMTP as it does for the API: the next login with it is refused. Give each application its own key, so you can stop one without touching the others.

WordPress

WordPress sends through PHP’s mail() by default, which often ends up in spam. The free WP Mail SMTP plugin sends through an SMTP server instead.

1. Install and activate WP Mail SMTP, then open WP Mail SMTP › Settings.
2. From Email: an address on your verified domain, for example shop@yourdomain.com. Tick Force From Email, so other plugins (WooCommerce, forms) cannot use a different address.
3. Mailer: Other SMTP.
4. SMTP Host smtp.azimea.com, Encryption TLS, SMTP Port 587, Auto TLS on.
5. Authentication on, SMTP Username azimea, SMTP Password your API key.
6. Save, then send a test from WP Mail SMTP › Tools › Email Test.

The plugin stores the password in the WordPress database. To keep the key out of it, define the settings in wp-config.php instead; the plugin then shows them as locked:

define( 'WPMS_ON', true );
define( 'WPMS_MAILER', 'smtp' );
define( 'WPMS_SMTP_HOST', 'smtp.azimea.com' );
define( 'WPMS_SMTP_PORT', 587 );
define( 'WPMS_SSL', 'tls' );
define( 'WPMS_SMTP_AUTH', true );
define( 'WPMS_SMTP_USER', 'azimea' );
define( 'WPMS_SMTP_PASS', 'azm_live_…' );

PrestaShop

1. Open Advanced Parameters › E-mail.
2. Choose Set my own SMTP parameters (for advanced users ONLY).
3. SMTP server smtp.azimea.com, SMTP username azimea, SMTP password your API key, then the encryption and port for your version:
   • PrestaShop 9: Encryption TLS, Port 465. Its “TLS” opens the connection already encrypted, so with port 587 the connection fails.
   • PrestaShop 8 and 1.7: Encryption TLS, Port 587, or Encryption SSL, Port 465.
4. Save, then use Send a test email at the bottom of the page.

PrestaShop sends from the shop’s own email address: make sure it is on your verified domain, or the test is refused with 550 5.7.1.

OpenCart

1. Open System › Settings, edit your store and go to the Mail tab.
2. Mail Engine SMTP.
3. SMTP Hostname ssl://smtp.azimea.com, SMTP Port 465, SMTP Username azimea, SMTP Password your API key. The ssl:// prefix is how OpenCart opens an encrypted connection; tls://smtp.azimea.com with port 587 works too.
4. Save. OpenCart sends from the store’s E-Mail on the Store tab: it must be on your verified domain.

Magento

From Magento 2.4.7 (and Mage-OS) SMTP is built in; older versions need an SMTP extension, configured with the same values.

1. Open Stores › Configuration › Advanced › System › Mail Sending Settings.
2. Transport SMTP, Host smtp.azimea.com, Port 587.
3. Username azimea, Password your API key, Auth LOGIN, SSL TLS.
4. Save. The sender addresses under Stores › Configuration › General › Store Email Addresses must be on your verified domain.

Shopware

1. Open Settings › System › Mailer and choose SMTP server.
2. Host smtp.azimea.com, Port 587, Encryption TLS (or Port 465 with Encryption SSL).
3. Username azimea, Password your API key, Authentication method login.
4. Save. The sender address in Settings › Shop › Basic information must be on your verified domain.

Any other software

Most tools have the same fields under another name: host or server, port, security (choose STARTTLS or TLS for 587, SSL/TLS for 465), username and password. If the tool offers only “SSL”, use port 465; if it offers “TLS” or “STARTTLS”, use 587. A few tools, PrestaShop 9 among them, mean “TLS from the first byte” by “TLS”: if port 587 fails with a TLS error such as “wrong version number”, use port 465.

From your own code, any SMTP library works:

PHP

use PHPMailer\PHPMailer\PHPMailer;

$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = 'smtp.azimea.com';
$mail->Port = 587;
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->SMTPAuth = true;
$mail->Username = 'azimea';
$mail->Password = getenv('AZIMEA_API_KEY');
$mail->CharSet = 'UTF-8';

$mail->setFrom('orders@yourdomain.com', 'Your Shop');
$mail->addAddress('emma@example.com', 'Emma');
$mail->Subject = 'Your order 1042 is confirmed';
$mail->isHTML(true);
$mail->Body = '<p>Hi Emma,</p><p>Thank you for your order 1042.</p>';
$mail->addCustomHeader('X-Azimea-Idempotency-Key', 'order-1042-confirmation');
$mail->send();

Node

import nodemailer from 'nodemailer';

const transport = nodemailer.createTransport({
  host: 'smtp.azimea.com',
  port: 587,
  secure: false, // STARTTLS on 587; use port 465 with secure: true for SSL/TLS
  requireTLS: true,
  auth: { user: 'azimea', pass: process.env.AZIMEA_API_KEY },
});

const info = await transport.sendMail({
  from: '"Your Shop" <orders@yourdomain.com>',
  to: '"Emma" <emma@example.com>',
  subject: 'Your order 1042 is confirmed',
  html: '<p>Hi Emma,</p><p>Thank you for your order 1042.</p>',
  headers: { 'X-Azimea-Idempotency-Key': 'order-1042-confirmation' },
});
console.log(info.response); // 250 2.0.0 Ok: queued as 01a1…

Python

import os, smtplib
from email.message import EmailMessage

message = EmailMessage()
message["From"] = "Your Shop <orders@yourdomain.com>"
message["To"] = "Emma <emma@example.com>"
message["Subject"] = "Your order 1042 is confirmed"
message["X-Azimea-Idempotency-Key"] = "order-1042-confirmation"
message.set_content("Thank you for your order 1042.")
message.add_alternative("<p>Hi Emma,</p><p>Thank you for your order 1042.</p>", subtype="html")

with smtplib.SMTP("smtp.azimea.com", 587) as smtp:
    smtp.starttls()
    smtp.login("azimea", os.environ["AZIMEA_API_KEY"])
    smtp.send_message(message)

C#

using MailKit.Net.Smtp;
using MailKit.Security;
using MimeKit;

var message = new MimeMessage();
message.From.Add(new MailboxAddress("Your Shop", "orders@yourdomain.com"));
message.To.Add(new MailboxAddress("Emma", "emma@example.com"));
message.Subject = "Your order 1042 is confirmed";
message.Headers.Add("X-Azimea-Idempotency-Key", "order-1042-confirmation");
message.Body = new TextPart("html") { Text = "<p>Hi Emma,</p><p>Thank you for your order 1042.</p>" };

using var smtp = new SmtpClient();
await smtp.ConnectAsync("smtp.azimea.com", 587, SecureSocketOptions.StartTls);
await smtp.AuthenticateAsync("azimea", Environment.GetEnvironmentVariable("AZIMEA_API_KEY"));
var answer = await smtp.SendAsync(message); // "2.0.0 Ok: queued as 01a1…"
await smtp.DisconnectAsync(true);

What happens to your message

Azimea reads the message you submit and sends it as if it had come through POST /sending/emails:

• Who receives it is decided by the SMTP envelope (RCPT TO), as in every mail server. An envelope address that is also in the To: or Cc: header keeps that role and its display name; one in neither header is a Bcc. A header address that is not in the envelope receives nothing.
• At most 50 recipients per message. The 51st RCPT TO is answered 452; send the rest in another message.
• If the message has no To: header (undisclosed-recipients) and a single recipient, that recipient becomes the To address. With several recipients and no To:, the message is refused, rather than showing one Bcc address to the others.
• Content: the subject, the HTML and plain-text parts, attachments and inline images (cid:) are kept. A forwarded message travels as an .eml attachment. The same limits as the API apply: a subject of up to 300 characters, at most 10 attachments of 5 MB together, and 10 MB for the whole message (announced with SIZE).
• Headers: your X-… headers, In-Reply-To and References are passed on, up to 20 of them (more is refused with 554). Azimea writes its own Message-ID, Date, Return-Path and DKIM signature; the rest of your headers, including X-Mailer, are dropped.
• Tracking follows your company’s tracking settings, unless the message says otherwise (below).

Options in headers

What the API takes as JSON fields, the relay takes as X-Azimea-… headers. They are read and removed: the recipient never sees them.

Header	Example	Same as the API’s
X-Azimea-Idempotency-Key	order-1042-confirmation	Idempotency-Key: a repeat with the same key and content sends nothing new
X-Azimea-Tags	kind=order; vip	tags (a piece without = is a tag with an empty value)
X-Azimea-Metadata	order_id=1042; channel=web	metadata, returned in webhooks
X-Azimea-Track-Opens	false	tracking.opens
X-Azimea-Track-Clicks	false	tracking.clicks

An idempotency key matters more over SMTP than over the API: if the connection drops after the message was sent but before the 250 reached your software, it will usually send the message again.

Answers and what to do

250 means the message is saved and queued, not yet delivered. Its text carries the submission id, the same id that GET /sending/emails/{id} and the delivery webhooks use. What happens next (delivered, bounced, complaint) is reported there and in the dashboard, not over SMTP.

A 4xx answer is temporary: your software keeps the message and tries again later. A 5xx answer is final: it stops and usually shows the error to whoever sent the email. The text after the code carries Azimea’s error code, the same one the API returns.

Answer	What it means	What you do
250 2.0.0 Ok: queued as …	Accepted and queued.	Keep the id if you want to follow the email.
530 authentication required	The message was sent before logging in.	Turn authentication on.
535 authentication failed	The key is wrong, revoked or expired, or has no emails:send permission. After 10 failures in 10 minutes, the sending IP address is refused for 15 minutes, even with a right key.	Check the key in Settings › API keys and that the username/password fields are not swapped.
452 4.5.3 Too many recipients	More than 50 recipients in one message.	Split the recipients into several messages.
552	The message is larger than 10 MB.	Send fewer or smaller attachments, or a link to the file.
550 5.7.1 Sender not allowed: …	The From: address is not on a verified domain of yours (deliverability.sender_domain_not_verified), or no sender is set.	Send from an address on a verified domain.
554 5.6.0 Message refused: …	The content breaks a limit: for example Subject: validation.required, To: validation.required, or an attachment the API would refuse.	Correct the field the answer names. Sending it again unchanged gets the same answer.
554 5.6.0 Message refused: sending.idempotency_conflict	The X-Azimea-Idempotency-Key was already used for a different message.	Use a new key for a new message; keep the same key only to retry the same one.
451 4.7.0 Too many messages for this key	More than 600 messages in a minute from one key.	Nothing: your software retries later. Spread large sends out.
451 4.3.0 Temporary failure	A problem on Azimea’s side.	Nothing: your software retries later.

An address that bounced, complained or is on the protective list is still accepted with 250: like the API, the relay records it as Suppressed instead of sending. See why an email was not sent.

Related

• Send your first email: the same sending from code, with JSON.
• Webhooks: hear back about deliveries, bounces and complaints.
• Sending and deliverability: domains, senders and the daily cap.