Mail API

Mail API makes your email provider's HTTP API the email transport of EmDash. Sign-in links, invites and plugin email go out through Brevo, Mailgun, Postmark or another service, with no SMTP server.

Features

• 10 providers: Brevo, Mailgun, Mailjet, Maileroo, Postmark, Mailchimp Transactional (Mandrill), Resend, SendGrid, MailerSend and Scaleway TEM.
• Verified senders: pick an address or a domain your provider has verified, or type one.
• Account status: plan, credits, quotas and reputation, read from the provider API.
• Errors you can act on: the provider's own message, with the HTTP status, the error code, a hint, a link to the page that fixes it and the raw response.
• Retry queue: when the provider is down or rate-limits, email waits in an encrypted queue and is resent with a growing delay.
• History and logs: every send with its status, message ID, attempts and duration, with filters, Resend, a 14-day chart and a dashboard widget.
• Test form on each provider's page.
• Encrypted: API keys are EmDash secrets, kept email content is encrypted, and sign-in email is never kept.
• Admin in English, French and German, usable on a phone.

Providers

Provider Credentials Senders listed Account status Brevo API key Addresses Plan, credits Mailgun API key, domain, region Domain Domain state Mailjet API key, secret key Addresses, domains No Maileroo Sending key No No Postmark Server token No Server, mode Mailchimp Transactional Mandrill key Domains Reputation, quota Resend API key Domains Plan, quotas SendGrid API key Addresses, domains Plan, credits MailerSend API token Addresses, domains API quota Scaleway TEM Secret key, project ID Domains Offer, usage

Where senders are not listed, type the address.

Do I need an SMTP server?

No. Mail API calls the provider's HTTP API over HTTPS, so it also works where SMTP is not available, such as Cloudflare Workers.

EmDash's "Send test email" only says "Failed to send test email".

Use the Send a test email form on the provider's page: it shows the provider's message, a hint and the raw response. The error is also in Logs and in the server log.

The sender list is empty, or shows HTTP 401 or 403.

The key can send but not list senders. Resend needs a Full access key, SendGrid read access to Sender Authentication and User Account, MailerSend Domains and Sender identity, Scaleway TransactionalEmailReadOnly, and Mailgun the account key rather than a domain sending key. You can still type the sender address.

The error says the IP address is not allowed.

Add your host's outgoing IP to the provider's allowlist, or turn the restriction off. The error links to the right page.

What happens when the provider is down?

Network errors, timeouts, HTTP 429 and 5xx put the email in an encrypted queue. It is retried after 1, 5, 15 and 30 min, then 1 h, 2 h and every 4 h, through the provider active at that time. Sign-in email expires after 15 minutes, other email after 24 hours. Permanent errors, such as an invalid key or a rejected recipient, are not retried.

The queue never runs.

Open the Security tab of Mail API: it lists the scheduled tasks and has a Repair button. On Cloudflare, check the cron trigger and the scheduled handler.

Is the content of my email stored?

Only while it waits in the queue, or in the history if you turn on Keep email content in the history. It is encrypted in both cases. Sign-in and invite email is never kept after sending.

Can I use several providers?

Yes. Configure several and click Activate on the one that sends. During an outage, activate another one: queued email is resent through it.

Reporting a vulnerability

Email psilbad@devbit.me. Please do not open a public issue first.

Permissions

• Network requests, limited to the provider API hosts: api.brevo.com, api.mailgun.net, api.eu.mailgun.net, api.mailjet.com, api.us.mailjet.com, smtp.maileroo.com, api.postmarkapp.com, mandrillapp.com, api.resend.com, api.sendgrid.com, api.eu.sendgrid.com, api.mailersend.com, api.scaleway.com.
• Email transport: EmDash hands its outgoing email to the plugin, which sends it through the active provider.

The plugin runs in EmDash's sandbox and can reach nothing else.

API keys

API keys are EmDash secret settings, encrypted with AES-GCM under the site's EMDASH_ENCRYPTION_KEY. A saved key never goes back to the browser: the admin shows only its last 5 characters. Any configured secret that a provider echoes in an error message is masked.

Data stored

• History: recipient, subject, provider, status, message ID, attempts, duration and error. Deleted after 30 days by default.
• Email content: kept only while the email waits in the queue, or in the history when you turn that on. It is encrypted with AES-GCM under a random 256-bit key, itself stored as an EmDash secret. Sign-in and invite email is never kept after sending.
• Logs: failures, queue runs and purges, deleted with the history.
• Verified senders and account status: cached in plugin storage with a fingerprint of the settings, never a key.

Email goes only to the active provider's API. Nothing else leaves the site.

Public route

One route is public: GET /_emdash/api/plugins/apimail/logo?p=<provider>. It serves the provider logos bundled in the plugin and reads no data.

Admin

The admin pages use a private route: before the plugin runs, EmDash requires a signed-in user allowed to manage plugins and the CSRF header.

0.3.1

• Three provider cards per row instead of two: a tighter list on a desktop.
• A Website link on each provider card, opened in a new tab.
• Set as default is now Activate, short enough for a card on a phone.
• A provider page opens at once from the saved data, with its age. The provider is only called when a key is saved or with Refresh from , and a message says how long the call took.

0.3.0

• Set as default button on the card of each configured provider.
• A failed read of verified senders or account status is written to the logs and retried at the next page load, unless the key lacks the permission.
• The sender list shows when it was read, also after an error.
• Admin pages fit a phone: two provider cards per row, at most three statistic cards, long values on their own line, fewer history columns.
• Shorter menu entries: History, Queue, Logs.
• Plain hyphens instead of long dashes in labels, logs, errors and the test email subject.
• Smaller bundle: provider logos are lossless WebP tiles.
• Registry listing: description, installation, FAQ, changelog and security tabs, and a banner.

0.2.0

• Pick a verified sender from the provider: a verified address, any address on a verified domain, or manual entry. In the Sender tab and in each test form.
• Account status on each provider's page: plan, credits, quotas and reputation.
• A test no longer needs a configured sender, and Use as the default sender keeps the one that worked.
• A saved key shows its last 5 characters.
• German admin.

Requirements

• EmDash 1.3.0 or later with a plugin sandbox runner: Cloudflare Worker Loader (Workers Paid plan), or @emdash-cms/sandbox-workerd on Node.js.
• EMDASH_ENCRYPTION_KEY on the site: it encrypts the API keys. Create one with npx emdash secrets generate, and on Cloudflare store it with wrangler secret put EMDASH_ENCRYPTION_KEY. Keep a copy in a secret manager: a database backup is useless without it.
• A scheduler for the retry queue: built in on Node.js. On Cloudflare, a * * * * * cron trigger and the scheduled handler (the EmDash templates include both).
• An account and an API key with one of the supported providers.

Install

1. Install Mail API from the plugin registry.
2. Review the permissions and confirm: requests to the provider API hosts only, and delivery of EmDash email.

From npm instead: pnpm add @devbitme/emdash-plugin-apimail, then add the default import to sandboxed: [...] in the emdash() integration of astro.config.mjs.

Set up

1. In the admin, open Mail API, then Configure on your provider.
2. Paste the key(s) and save. The Account section confirms that the key works.
3. In Send a test email, pick a verified sender, enter your address and send. Leave Use as the default sender on to keep that sender.
4. Click Activate on the provider's card in the list.
5. If several email transports are installed, select Mail API under Settings → Email. Under astro dev, EmDash's console transport counts as one.

Settings

The Queue & history tab sets how long email may wait in the queue (15 minutes for sign-in email, 24 hours for the rest by default), whether to keep email content, and how long history and logs are kept (30 days by default).

Full documentation: https://git.devbit.me/devbit.me/emdash-plugin-apimail