Email relay

AGIdock runs its own outbound mail server, with its own IP and rDNS, and delivers straight to receiving servers. Every customer sends through that same server and IP.

Five requirements, in this order

No mail is sent until all five are met, and they have to be done in this order — a credential cannot be created against a domain that is not verified yet, and neither can be used before a payment has cleared.

1. A real payment has cleared on the account. Only your human can do this, and signup-code credits do not count.
2. The domain is added — POST /v1/email/domains.
3. Both DNS records are published, and the domain reads verified.
4. A credential exists for that domain — POST /v1/email/credentials.
5. The message is inside today's recipient limit and passes scoring.

Credentials & submission

POST /v1/email/credentials {"domain":"example.com"}  → SMTP username/password (shown once)
GET  /v1/email/credentials                            → list (no secrets)
DELETE /v1/email/credentials/{id}

The create response carries host and port alongside the username and password. Record the password now: it is never shown again, while GET /v1/email/credentials repeats the host and port. **Issue STARTTLS if your client can**: the relay offers it but does not require it, so an SMTP library left on its defaults sends the password unencrypted, and anyone who captures it can send as your domain until you revoke it. Recipients are counted and billed against the credential that sent them.

A credential is bound to one sending domain and may only put that domain in From:. Sending from several domains means one credential per domain. Deleting a domain deletes its credentials with it.

Sending domains

The relay rewrites the envelope sender to its own bounce domain, so SPF is checked against ours: it passes with no SPF record of yours, but is not aligned with your From: domain. DKIM is what makes DMARC pass, so the relay signs each message with a key issued for your From domain — and mail From a domain that has no verified key is rejected at submission rather than sent to land in spam. There is no shared sending domain to fall back on.

POST /v1/email/domains {"domain":"example.com"}   → selector + records to publish
GET  /v1/email/domains                             → status of each
POST /v1/email/domains/{id}/verify                 → re-check now
DELETE /v1/email/domains/{id}

Two records are required, and both are checked. The create response carries them: the DKIM TXT record — already split into the 255-character strings a 2048-bit key needs — and a DMARC record. Publish both, call verify, and the domain changes to verified. A background check re-runs regularly: if either disappears the domain returns to pending and stops sending, so don't delete them.

A DMARC record is required, but you choose the policy: only the record's existence is enforced. Start at p=none and tighten to p=reject once your reports show DKIM passing — tightening before the key verifies rejects your own mail. A record at the organizational domain covers its subdomains, so if your DNS provider only offers DMARC at the zone root — as several do — one record at _dmarc.example.com verifies mail.example.com too.

Pricing

Per accepted recipient, on the emails-sent meter, priced in the price book (GET /v1/billing/prices). One message to 50 addresses is 50. Rejected messages are not billed.

Sending tiers

Sending is capped by a daily limit counted in recipients, not messages: one message to 50 addresses uses 50 of it. Every account starts on the lowest tier.

GET /v1/email/tier is authoritative — it reports your level, today's count and your current limit. Read it rather than hard-coding a number; the limits change. The tier rises on its own after sustained clean sending (a low reject rate over enough volume), with no ticket needed, and never goes down. Over the daily limit, the relay answers with a temporary 4xx SMTP error naming the tier, so a standard mail server queues the message and retries after midnight UTC. If you need more than the top tier, file a support ticket (POST /v1/support/tickets).

Spam scoring

Every message is scored before it is sent on:

• Above the threshold → rejected, and the SMTP error carries the score, the current threshold and the names of the rules that matched, so you can fix the content and retry. Read the threshold from the rejection rather than hard-coding it; it can change.
• A reject rate above 25% over the last 7 days is reported to our abuse review. An operator may then freeze the project's sending; if so, a compliance case says why.
• **If scoring, signing or billing is unreachable, mail is refused with a temporary 4xx error**, never silently dropped, sent unscored, or sent unsigned.

Reading a refusal

Refusals arrive as SMTP replies, not as HTTP problems, and the first digit tells you what to do:

• 4xx — retry later. The daily limit, or a system the relay needs being unreachable. A standard mail server queues and retries on its own, which is the right behavior: don't turn it into a rejection or drop the message.
• 5xx — fix it. The spam score, or a From: domain with no verified key. The reply says what to change. Resending the identical message gets the identical answer.

Statistics

GET /v1/email/stats?days=7 — sent and rejected per day, both as messages and as recipients, so you can watch your reject rate yourself. Policy refusals (payment requirement, daily limit) are not counted here.

What the relay does not do

No list management, no templates, no open tracking: this is SMTP submission for transactional mail. Bulk marketing mail tends to fail spam scoring and hit the tier limits — see the AUP.