Connecting your sending tool to the Infrabox SMTP relay

Your sending tool wants a host, a port, a username and a password. It does not care what happens after that. This guide covers what to type, and then what actually happens to a message once the relay has it — because the second part is what you will need when something returns a code you do not recognise.

The settings

Every mailbox uses the same host and port. Only the username and password differ.

Some tools label the encryption field “TLS” and some say “STARTTLS”. On port 587 they mean the same thing: connect in the clear, then upgrade before anything sensitive crosses the wire. If a tool offers you SSL on port 465, it is offering a different thing and the relay does not listen there.

The password is shown once, and that is not a UI choice

When you issue a relay credential you get a 24-character password, once. It is not retrievable afterwards. The reason is worth stating precisely, because “we choose not to show it again” and “we cannot show it again” are very different promises: the password is stored as a bcrypt hash, so there is no code path that could return it. Losing it means rotating it, not recovering it.

Rotation overwrites the credential immediately. There is no overlap window where both the old and the new password work, so rotate when your tool is ready to take the new value, not before.

What happens to a message

The relay speaks SMTP to your tool and the Gmail API to Google. In between it does as little as possible, on purpose.

1. Your tool connects, upgrades to TLS, and authenticates with the relay credential.
2. The message bytes are buffered in memory. Nothing is written to disk and the message body is never logged.
3. A short-lived access token for that specific mailbox is minted through domain-wide delegation.
4. The original bytes are handed to the Gmail send API unchanged, base64-encoded, with no re-serialisation.
5. Google’s message ID comes back and is returned to your tool in the 250 acceptance line. The buffered bytes are dropped.

Why the message is forwarded byte-for-byte

This is the single most consequential decision in the relay. Anything that parses a message and rebuilds it will subtly change it: header order, encoding of the boundary parameters, whitespace. Three things break when that happens.

• Your Message-ID changes, and reply threading in your sequencer stops working, because threading is matched on that value.
• List-Unsubscribe can be dropped or reordered, which matters to receivers that look for it.
• Custom X- headers your tool relies on for open tracking and campaign attribution disappear.

Forwarding the exact bytes avoids all three. It also means the relay cannot silently “fix” a malformed message for you — if your tool produces something Google rejects, you get the rejection rather than a quietly rewritten message.

The one header Google does enforce

The From header has to be the authenticated mailbox. Google checks this, not the relay, and refuses anything else. Sending tools that let you set a display From different from the connection identity will produce a rejection here. The envelope sender is a separate matter — the relay does not forward your MAIL FROM, because Gmail derives the envelope sender from the authenticated user regardless.

Limits

• Message size: 10 MB. The constraint is the Gmail API’s upload path rather than SMTP.
• Daily sending: 2,000 messages per mailbox by default, counted from midnight to midnight UTC — not your local midnight, which is worth knowing if your schedule assumes otherwise. Only successful sends count against it.

That cap is a technical ceiling, not a recommendation. Sending anywhere near it from a new mailbox is a good way to get the mailbox suspended. Google applies its own limits underneath, and the ramp rules in section 4 of the Acceptable Use Policy apply well below the ceiling.

Reading the codes it sends back

The relay maps Google’s answers onto SMTP codes your tool already understands. The mapping is biased in one direction on purpose: anything the relay cannot confidently classify comes back as a 4xx, because most sending tools treat a 5xx as “this address is permanently dead” and will stop retrying a mailbox that was only briefly unavailable.

Testing it by hand

Before wiring a tool up, it is worth confirming the credential works at all. Any SMTP client will do; the useful part is what you should see.

220 Infrabox SMTP relay
EHLO test
250-STARTTLS
250 AUTH PLAIN LOGIN
STARTTLS
220 Ready to start TLS
AUTH LOGIN
...
235 Authentication successful
MAIL FROM:<you@yourdomain.com>
250 OK
RCPT TO:<someone@example.com>
250 OK
DATA
...
250 Accepted <gmail-message-id>

The 250 Accepted line carries Google’s own message ID, which means the message did not merely reach the relay — it reached Gmail and was accepted there. A relay that answered 250 before talking to Google would be lying to your tool about delivery, so the acceptance is deliberately sent last.

When it will not connect

• Authentication fails immediately. The credential is wrong or has been rotated. Issue a new one; there is nothing to recover.
• Authentication works, sending returns 550 5.1.1. The mailbox is not active yet. A mailbox mid-provisioning has a credential endpoint but nothing to send through. Check its status.
• Everything works, then 452 partway through a campaign. The daily cap. Spread the volume across more mailboxes rather than waiting it out.
• Persistent 451s. Transient by definition, but if they persist it is on the Infrabox side rather than yours — a delegation or platform problem, not something to fix in your tool.