Mail Relay

What Mail Relay does

Your application describes a message and Pierrr sends it. It never holds sending credentials, so a compromised container cannot write in anyone's name. Mail Relay is for transactional emails: sign-in links, password resets, receipts, notifications tied to an action of the recipient.

Mail Relay is not meant for newsletters or bulk sending. A project whose emails are widely reported as unwanted or fail to deliver has its sending suspended.

Send an email

From a container of your project, send a POST request to the Pierrr mail relay. The relay address is the one on your project network; the sending project is recognized automatically, you declare nothing.

The body is JSON: `to` (one recipient), `subject`, `text`, and optionally `html`, `fromName` (the display name) and `attachments`. The sending address is Pierrr's; only the display name changes.

Add an `idempotencyKey`: replaying a call after a timeout returns the original send instead of sending a second sign-in link, and does not count against your quota.

On your own server

A project running on a server connected through Pierrr Agent sends its emails exactly the same way: same relay address, same request body, same monthly quota shared by the organization, same response codes. Nothing to change in your code when you move from one hosting to the other.

On your server, the relay is installed by the agent and only listens on your projects' networks: no port is opened to the internet. Each message goes to Pierrr over the agent's encrypted connection, and Pierrr checks that the project writing it does run on that server. Sending is rate-limited per project on the server, then by your plan's quota.

This needs a recent version of the agent: until it is installed, the project's Networks tab says so and offers the update.

Monthly quota

Every plan includes a number of emails per month: 50 on Free, 1,000 on Starter, 3,000 on Pro, 10,000 on Business. The counter is shared by every project of the organization and resets on the 1st of each month at 00:00 UTC.

An email counts once it is accepted. A send that fails on our side consumes nothing, and neither does a replay with the same key.

At 80% and then 100%, the organization's owners, maintainers and billing role are notified in the app and by email. You follow usage in the Networks tab of your projects.

When the quota is reached, further sends are refused with status 429 and the code `quota_exceeded`. The response gives the counter, the limit and the resume date (`resetsAt`), and the `Retry-After` header gives the delay in seconds. A higher plan restores sending right away.

The Free plan

The Free plan includes Mail Relay with a few safeguards that protect deliverability for everyone:

• the organization owner has verified their email address, and the project has already deployed successfully;
• rate and recipient limits apply on the Free plan to protect sending reputation;
• a send refused for that reason is refused with an explicit code, and the `Retry-After` header says when to try again;
• the display name cannot reuse Pierrr's or a well-known brand's.

Response codes

A refused send is always refused explicitly, with a stable code in `reason`.

• 201: accepted, the message identifier is returned.
• 400: attachment refused (`invalid_attachment`) or display name refused (`reserved_sender`).
• 403: project not eligible (`not_eligible`) or sending suspended (`suspended`).
• 429: monthly quota reached (`quota_exceeded`), Free plan rate exceeded (`rate_limited`, with `Retry-After`) or too many different recipients (`too_many_recipients`).
• 502: the message could not be handed to our carrier; 503: sending is not available.

Attachments

Up to 5 attachments, 500 KB each and 700 KB in total. Accepted types: PDF, text, CSV, JSON, PNG, JPEG, GIF and WebP. The content is checked against the declared type, and HTML pages or archives are refused.

What Pierrr keeps

Only metadata: project, recipient, status and message identifier. Never the subject or the content, since they carry valid sign-in links. This metadata is deleted after 30 days.