Quickstart

Your first email through Postilio, from a domain of your own. You need a Postilio organization and access to the DNS of the domain you send from. The DNS step is the slow one; the rest takes a few minutes.

1. Add your sending domain

In the portal, open Domains and add the domain you send from, for example mail.example.com. Postilio shows two CNAME records; create both at your DNS provider:

Copy the exact values from the portal: the selector and the token are your domain's own. Postilio checks the records every 10 minutes, or right away when you press Check now. Once they are found the domain is verified, and you can send from any address on it. Sending domains explains the records.

2. Create an API key

Open Keys & SMTP and create a key. Start with a test key (pk_test_…): its messages are checked like a live key's (sender domain, restrictions, suppression list) but never sent, so you can try everything below safely. The key is shown once; store it as an environment variable:

export POSTILIO_KEY=pk_test_...

3. Send an email

Send to the simulator: with a test key, delivered@simulator.postilio.eu gets a simulated delivery. Use an address on your own verified domain as the sender.

curl https://api.postilio.eu/v1/emails \
  -H "Authorization: Bearer $POSTILIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <no-reply@mail.example.com>",
    "to": ["delivered@simulator.postilio.eu"],
    "subject": "Welcome to Acme",
    "text": "Hi Ada, your account is ready.",
    "tag": "welcome"
  }'

Postilio answers 202 Accepted with one message id per recipient:

{ "ids": ["01a10ce5-a09a-788b-9243-d7c9c59773d2"], "suppressed": [] }

The same in Node:

// Sends an email with the Postilio API: node send.mjs (Node 18 or later, no packages needed).
const response = await fetch('https://api.postilio.eu/v1/emails', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTILIO_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'Acme <no-reply@mail.example.com>',
    to: ['delivered@simulator.postilio.eu'],
    subject: 'Welcome to Acme',
    text: 'Hi Ada, your account is ready.',
    tag: 'welcome',
  }),
});
const result = await response.json();
if (!response.ok) {
  throw new Error(`Postilio answered ${response.status}: ${JSON.stringify(result)}`);
}
console.log(result.ids[0]); // one id per recipient, in the order of "to"

And in C#:

// Sends an email with the Postilio API: dotnet run Send.cs (.NET 10, no packages needed).
// A file-based app is compiled ahead of time, without reflection-based JSON; in a project, leave this line out.
#:property PublishAot=false
using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://api.postilio.eu/") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("POSTILIO_KEY"));

var response = await http.PostAsJsonAsync("v1/emails", new
{
    from = "Acme <no-reply@mail.example.com>",
    to = new[] { "delivered@simulator.postilio.eu" },
    subject = "Welcome to Acme",
    text = "Hi Ada, your account is ready.",
    tag = "welcome",
});
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException($"Postilio answered {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");
}
var result = await response.Content.ReadFromJsonAsync<SendEmailResponse>();
Console.WriteLine(result?.Ids[0]); // one id per recipient, in the order of "to"

record SendEmailResponse(Guid[] Ids, string[] Suppressed);

4. Follow what happened

Look the message up by its id, or open Messages in the portal:

curl https://api.postilio.eu/v1/emails/$EMAIL_ID \
  -H "Authorization: Bearer $POSTILIO_KEY"

The answer has the message's status and every event, from accepted to delivered. Rather than asking, you can let Postilio tell you: see Webhooks.

5. Go live

Create a live key (pk_live_…) and send to a real address. A new organization starts in the sandbox: live mail goes only to your team and to addresses on your verified domains, at most 100 recipients a day and 10 a minute. The Sandbox page in the portal shows how far you are and how to ask for full access. Errors and limits has the details.

Next: Sending email for everything a message can hold, and over SMTP; Authentication and API keys for scopes and restrictions.