Before you start

1. Open Settings → Connections.
2. Click Add connection and choose the Email type.
3. Pick the provider/transport that matches your account.
4. Give the Connection a clear name, for example Resend production or Mailgun EU.
5. Save, then click Test send.
6. If the test succeeds, go to Aliases and map transactional_email to this Connection.

Generic SMTP

Use SMTP when you have your own mail server or a host-provided relay.

Fields you need:

Field	Example	Notes
Host	smtp.example.com	Your mail server hostname.
Port	587 or 465	587 usually uses STARTTLS; 465 usually uses SSL.
Encryption	STARTTLS, SSL, or None	Match your port.
Username	you@example.com	Often the full email address.
Password	app-specific password	Use an app password, not your login password.
From address	noreply@example.com	Must be allowed by the server.
From name	Birkly	Display name recipients see.

Common problems:

• Docker hosts often block outbound SMTP on port 25/587. If test fails with a network timeout, switch to an ESP or ask your host to open the port.
• Gmail / Outlook personal accounts require app-specific passwords and may have strict sending limits. For production sites, use a transactional ESP instead.
• Wrong encryption/port pair is the most common failure.

Resend

Resend is a transactional email service with a simple HTTP API.

Fields you need:

Field	Example	Notes
API key	re_xxxxxxxxxxxxxxxx	Create in Resend dashboard → API keys.
From address	onboarding@yourdomain.com	Must be a verified domain or a Resend-provided test address.
From name	Your site	Display name.

After saving:

1. Click Test send.
2. If the domain is not verified, Resend accepts mail only from a test address or may reject depending on your plan.
3. Add the Resend bounce/complaint webhook URL in Connections → Webhooks if you want automatic suppression updates.

Postmark

Postmark focuses on transactional email and provides clear delivery events.

Fields you need:

Field	Example	Notes
Server API token	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	From a Postmark server, not an account token.
From address	noreply@yourdomain.com	Must match a verified sender signature.
From name	Your site	Display name.

After saving:

1. Click Test send.
2. In Postmark, copy the inbound webhook URL from Connections → Webhooks and paste it into Postmark → Webhooks so bounces and spam complaints update Birkly’s suppression list.

Amazon SES

Birkly prefers the Amazon SES HTTPS API adapter. You can also use SES-SMTP credentials through the generic SMTP transport if you prefer.

Fields for the SES HTTPS API adapter:

Field	Example	Notes
Access key ID	AKIA...	IAM user with ses:SendRawEmail permission.
Secret access key	...	Stored encrypted.
Region	us-east-1	Your SES region.
From address	noreply@yourdomain.com	Must be a verified identity in SES.
From name	Your site	Display name.

IAM permission needed:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["ses:SendEmail", "ses:SendRawEmail"],
      "Resource": "*"
    }
  ]
}

After saving:

1. Click Test send.
2. SES in sandbox mode only sends to verified addresses. Move out of sandbox for production.
3. Configure SNS → HTTPS webhook to /api/webhooks/connections/{id} for bounce/complaint delivery.

Mailgun

Mailgun provides both US and EU endpoints.

Fields you need:

Field	Example	Notes
API key	key-xxxxxxxxxxxxxxxx	From Mailgun dashboard → Settings → API keys.
Domain	mg.yourdomain.com	Must be active in Mailgun.
Region	US or EU	Choose the region where your domain is hosted.
From address	noreply@mg.yourdomain.com	Must belong to the configured domain.
From name	Your site	Display name.

After saving:

1. Click Test send.
2. Add Mailgun webhook URLs for permanent fail and spam complaints in Connections → Webhooks.

DNS: SPF, DKIM, DMARC

Birkly does not generate DKIM keys for you; your provider does. The provider recipe is incomplete until DNS is correct:

1. Add the provider’s SPF include to your domain’s TXT record.
2. Add the DKIM record the provider gives you.
3. Add a DMARC policy record such as v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com.

The Email Connection checklist links to provider-specific DNS instructions. Incorrect DNS is the most common cause of messages landing in spam.

Choosing between providers

Choose this	When
Resend	Fastest setup, generous free tier, strong developer focus.
Postmark	Strictly transactional, excellent deliverability reputation, detailed events.
Amazon SES	Lowest cost at scale, already in AWS, comfortable managing IAM/SNS.
Mailgun	Need EU residency, complex routing, or existing Mailgun workflows.
SMTP	You already run a reliable mail server and cannot use an ESP.
Log	Local development only; never for production.