How to send transactional email from a Quake AI workload

Send password resets, receipts, and other per-user transactional email from an application running on a Quake AI instance by relaying through a third-party email provider over an authenticated submission port.

Before you start#

This procedure assumes you have:

• An application running on a Quake AI instance that needs to send email.
• A domain you control, with access to edit its DNS records at your registrar or DNS host.
• An account with one of the email providers compared below.

The application sends outbound connections only; it does not receive inbound mail. For inbound delivery, point your domain's MX records at your provider and follow the provider's inbound routing documentation.

Pick an email provider#

Each provider exposes an authenticated SMTP submission endpoint and an HTTP API. The SMTP path works the same from any language, so this page uses it as the common shape. Pick based on the workload:

The steps below apply to any of the four. Where the provider-side setup diverges, the per-provider tabs call out the difference.

Step 1. Create a sending credential at your provider#

Create an SMTP credential (a username and password pair) in the provider console, then record the submission host and port. Treat the credential as a secret from the moment you create it.

The submission endpoints share a common shape:

Port 587 uses STARTTLS to upgrade the connection to TLS. Port 465 carries TLS from the first byte. Both are authenticated submission ports. Use 587 unless your client library only supports implicit TLS, in which case use 465.

Step 2. Store the credential as an application secret#

Keep the SMTP username and password out of your source tree and out of your instance image. Inject them at runtime as environment variables, or read them from a secrets manager your application already uses.

# Set on the instance or in your deployment pipeline, not in source control.
export SMTP_HOST="smtp.postmarkapp.com"
export SMTP_PORT="587"
export SMTP_USERNAME="YOUR_SMTP_USERNAME"
export SMTP_PASSWORD="YOUR_SMTP_PASSWORD"

Step 3. Allow outbound submission traffic#

By default, a Quake AI security group permits the outbound traffic your instance needs to reach the provider. If you have tightened egress rules, add an egress rule that allows TCP to the submission port your provider uses (587 or 465).

openstack security group rule create \
  --egress --protocol tcp --dst-port 587 \
  --remote-ip 0.0.0.0/0 \
  YOUR_SECURITY_GROUP

For the Console procedure and the full set of options, see Create security group rules. Confirm that no rule on your instance blocks outbound port 587 or 465 before you move on.

Step 4. Configure your application or mail server to relay#

Point your application at the submission endpoint using the credential from Step 2. Configure it at the application layer if your code sends mail directly, or at the system layer if your services hand mail to a local mail server such as Postfix.

import os
import smtplib
from email.message import EmailMessage

message = EmailMessage()
message["From"] = "[email protected]"
message["To"] = "[email protected]"
message["Subject"] = "Your receipt"
message.set_content("Thanks for your order.")

with smtplib.SMTP(os.environ["SMTP_HOST"], int(os.environ["SMTP_PORT"])) as smtp:
    smtp.starttls()
    smtp.login(os.environ["SMTP_USERNAME"], os.environ["SMTP_PASSWORD"])
    smtp.send_message(message)

Step 5. Authenticate your sending domain in DNS#

Mailbox providers check three DNS records to decide whether to accept your mail. Add them at the DNS host for your sending domain. Your email provider generates the exact values; the records below show the shape.

• SPF authorizes the provider to send for your domain. Publish one TXT record at the domain root that includes the provider's SPF host:

example.com.  IN  TXT  "v=spf1 include:PROVIDER_SPF_HOST -all"

• DKIM signs each message so the receiver can verify it was not altered. Your provider gives you one or more CNAME or TXT records to publish under a selector subdomain:

SELECTOR._domainkey.example.com.  IN  CNAME  SELECTOR.dkim.PROVIDER_DOMAIN.

• DMARC tells receivers what to do when SPF or DKIM fails and where to send reports. Start with a monitoring policy, then tighten to quarantine or reject once your reports are clean:

_dmarc.example.com.  IN  TXT  "v=DMARC1; p=none; rua=mailto:[email protected]"

After you publish the records, verify them in your provider's domain settings. Each provider shows a verified status once the records resolve. DNS changes take effect after the record's TTL elapses.

Step 6. Send a test message and verify delivery#

Send one message to an address you control, then confirm it arrived and authenticated correctly.

# Quick check with swaks, an SMTP test client.
swaks --to [email protected] \
  --from [email protected] \
  --server "$SMTP_HOST:$SMTP_PORT" \
  --auth-user "$SMTP_USERNAME" \
  --auth-password "$SMTP_PASSWORD" \
  --tls

A successful run ends with a 250 response code from the provider. In the received message, view the original headers and confirm that SPF, DKIM, and DMARC each show a pass result. Your provider's dashboard also records the message as delivered.

Networking and floating IPs#

This pattern allocates zero floating IPs. The workload makes outbound connections only, to the provider's submission endpoint. An instance on a private network reaches the internet through its router's external gateway using source NAT, which covers outbound submission traffic without a floating IP. Allocate a floating IP only if a separate part of your application needs inbound reachability; sending transactional email does not.

See also#

• Sending mail (SMTP) with your virtual machine: request an exception to send directly from your instance's IP through a support ticket.
• Create security group rules: manage egress and ingress rules for your instance.
• Create a router: give a private network outbound internet access through an external gateway.
• Shared responsibility model: what Quake AI operates and what you operate.