Apps and the API

Connect an app

An app is a piece of your software that works with Mailroomly through its own keys. Administrators connect apps in Apps, which opens with What do you want to do?:

• Send email from my application opens Connect an app.
• Get events in my system goes to the Webhook step of an app. With several apps it asks Which app gets the events?; with none, you connect one first.
• Connect an AI agent connects an agent that works for the organization (AI agents) or, with As you, your own agent.
• Move over from Postmark is a three-step guide for code built for Postmark (Moving from Postmark).
• Move over from SendGrid is the same for code built for SendGrid (Moving from SendGrid).
• Move over from Mailgun is the same for code built for Mailgun (Moving from Mailgun).

Below come Your apps, each with whether its key has been used, its number of keys and Webhook on or No webhook, and, folded, For developers: Webhook deliveries and Send a test email as you. Ctrl K offers the same goals.

What do you want to do?, then your apps

Before an app sends, your organization needs a sending address: a verified domain or the free address (Addresses and domains).

Important

The key, starting with mp_live_, is shown only once. Copy it into the app's configuration or secret store: Mailroomly keeps only a hash and can't show it again. The code under Try it reads it from the MAILROOMLY_API_KEY environment variable, so copying the code never spreads the key.

Apps and keys

Open an app from Your apps. Its page has two tabs, Set up and Deliveries. Set up has three numbered steps, each marked Done once it is:

1. API key (to send): whether a key has been used, and the app's keys. Done after a key's first request.
2. Webhook (optional): where Mailroomly posts the app's events (Webhooks).
3. Send a test as this app: an email sent as the app to you only (Send a test email).

The steps of an app, with its keys

Create a key

Give each environment and each integration its own key, with only what it needs. Under Keys, choose Create key:

1. A Name, for example "Production".

2. The Permissions:

   Permission	Allows
   Send messages	Sending email: the REST API, the Postmark-compatible endpoints and MCP
   Read activity	Searching messages and their events
   List addresses	Listing the organization's addresses
   Read inboxes	Reading the addresses' conversations
   Reply from inboxes	Replying and forwarding from the addresses, and leaving drafts
   Leave drafts for approval	Leaving replies for a person to send, edit or discard, and handing conversations over. Without Reply from inboxes, the key never sends on its own.
   Read blocked addresses / Manage blocked addresses	Viewing / adding and removing blocked addresses
   Contacts	Adding and updating contacts and lists, and recording events that start automations (Contacts and lists)
   Campaigns	Everything Contacts allows, and templates, images, newsletters and automations, sending included. What the key starts waits 15 minutes while administrators can cancel it (Marketing from your apps and agents)

3. Which emails does this key reach? (below).

4. Restrict to specific types of email (optional): transactional, marketing, or both.

5. A Daily recipient limit (optional): how many recipients the key may send to per day, so a leaked or runaway key can't use your organization's whole allowance. Leave it empty for No limit of its own: your organization's limits still apply.

6. Choose Create key. Key created shows the key once, with sample code; copy it, then choose I’ve stored the key.

Each key's row shows its limit and Last used, which helps you find keys nobody uses. Change limit sets or removes the daily limit at any time. Over its limit, the key's sends are refused until midnight UTC, and administrators get one notice that day (notice). The limit counts every domain.

Which emails a key reaches

Change access, on the key's row, changes it at any time. The key keeps its secret, and the change applies from its next request.

Warning

Taking addresses from a key stops whatever uses them at once: sending from them is refused, and their email can't be read. Before you save, Mailroomly lists them, says which ones the key sent from in the last 30 days and which ones belong to the app, and asks you to confirm. Reading email isn't shown there, so a quiet address can still be in use.

Giving a key more tells every administrator (notice). Only a person signed in to Mailroomly changes what a key reaches; an agent can't (what stays with a signed-in person).

Replace or revoke a key

• Replace, for a lost or exposed key: a new key with the same name, permissions, scope and daily limit takes its place, and the old one is revoked at once. The new key is shown once. Whatever still uses the old key stops working until it has the new one. If the old key can't be revoked, the dialog says it still works and offers Revoke the old key.
• Revoke stops a key immediately.

Warning

Revoking cannot be undone: requests with the key fail at once. Replace the key in the app before you revoke the old one.

Delete an app

Delete app revokes all its keys at once and stops its webhooks; deliveries still waiting are marked Dead. Before you delete an app that owns addresses, give those addresses another owning app or their own webhook, on each address's page (Addresses and domains).

Send your first email

Apps send through the REST API with the key in the Authorization: Bearer header. With the key in the MAILROOMLY_API_KEY environment variable, and a sender on your verified domain:

curl https://app.mailroomly.com/api/v1/messages \
  -H "Authorization: Bearer $MAILROOMLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "Shop <hello@mail.example.com>", "to": ["customer@example.com"], "subject": "Your order", "text": "Thank you for your order."}'

Mailroomly answers 202 with the message's id and "status": "QUEUED": the email is accepted and goes out in the background. Follow it in Activity (A send's page) or through your webhook.

• from must be an address on a verified domain of your organization, within the key's scope.
• Give an html body, a text body, or both. Up to 50 recipients in all (to, cc, bcc).
• Add an idempotencyKey per business event (for example "invoice-2026-0042"): a retried request then returns the first result instead of sending twice.
• Recipients you have blocked are left out and listed in suppressedRecipients. When none remains, the answer is 422 ALL_RECIPIENTS_SUPPRESSED: don't retry.
• Up to 500 messages at once go to /api/v1/messages/batch.

Every field, error and limit is in the REST API reference. Code built for Postmark, SendGrid or Mailgun keeps its requests: Moving from Postmark, Moving from SendGrid, Moving from Mailgun.

Types of email

Every email is one of two types, and the type decides how it goes out:

• Transactional email always goes first.
• Marketing email gets an unsubscribe link and headers for each recipient: put {{unsubscribe_url}} in the body where the link should show. Send one message per recipient (/api/v1/messages/batch), so recipients don't see each other.
• Marketing needs a plan that includes it and an administrator's acceptance of the terms of service, can't be sent from the free address, and from your own domain needs the domain's DMARC record. A new account sends marketing in growing waves (Sending trust).
• A key can be restricted to one type with Restrict to specific types of email.

Campaigns and unsubscribes: Campaigns and marketing.

Webhooks

A webhook tells your app what happened to its email: Mailroomly posts each event to a URL of yours, signed so your app can check it comes from Mailroomly. Each app has one webhook URL, its format and the events it wants.

The signing secret. Under Advanced details, the Signing secret (to verify the webhooks you receive) starts with whsec_. It is not an API key: your endpoint uses it to check the signature that comes with every webhook. Reveal secret shows it. How to check the signature, with code: Webhooks reference.

The verification key. An app in the SendGrid-compatible format also shows, under Advanced details, its Verification key (SendGrid’s signed Event Webhook): your SendGrid event handler checks each webhook's signature with it, in place of the key SendGrid gave you (Moving from SendGrid).

Mailgun's signing key. In the Mailgun-compatible format, the signing secret is also the webhook signing key: your Mailgun handler checks each webhook with it, in place of the one Mailgun gave you (Moving from Mailgun).

Warning

Rotate secret replaces the secret at once, for every delivery from then on, retries included, and a SendGrid-compatible app's verification key with it. Update your endpoint first, or let it accept both secrets for a while; a new verification key goes in the handler right after rotating.

Your endpoint should answer with any 2xx within 10 seconds, and do its work afterward. Events can arrive more than once and out of order: use each event's id to ignore repeats.

An address can also post every email it receives to its own Inbound webhook URL, signed with its owning app's secret and in that app's format (Addresses and domains).

Deliveries and replay

Apps › For developers › Webhook deliveries lists every delivery to your apps' and addresses' webhooks; the Deliveries tab of an app shows only that app's. Filter by status, app and event:

Details shows the content sent, the attempts, the URL it last went to and your endpoint's last answer. For a received email, the content shown is a reference to the message: its text and attachments are added each time it is sent, not stored with the delivery.

A failed delivery is tried again 1 minute later, then after 5 minutes, 30 minutes, 2, 6, 12 and 24 hours. After the 8th attempt it is marked Dead, and administrators get the notice Webhook deliveries failed (notice). A URL that points to an internal network is refused, and its deliveries are marked Dead at once.

Retries and replays always go to the current webhook URL, so fixing the URL is enough. Once your endpoint works again, select deliveries and choose Replay … selected, or Replay all dead for this app: they go back to the queue and get the full retry schedule again. An agent with Manage apps lists them with list_webhook_deliveries and replays them with replay_webhooks.

Requests

Apps › For developers › Requests lists every call your apps and AI agents made, through the API or MCP, for the last 30 days, newest first: when, the call (the endpoint, or the MCP tool), its result, who made it (the app and its key, or the agent's token) and how long it took. An app's Calls tab shows only its own; in My agents, See its calls shows a token's.

Every call, with its result and why it failed

Filter by result (Only what failed), app or agent, channel (API or MCP) and period. Select a call to see its error code, the reason in plain words, the client it came from and its request ID; a call that sent an email links to it. What a call sent is never kept with it: the email keeps its own content.

Why it was refused, in plain words, with its details

Administrators see every call of the organization. Anyone else sees the calls of their own agents, and an app's key or an agent's token reads only its own.

Send a test email

There are two tests, for two questions:

Send a test email sends one email as you. It belongs to no app, so it never reaches your apps' webhooks. Choose the sender in From (one of your addresses, or Other address… on a verified domain), the recipients, the subject, the Type, the HTML body, the Text body or both, and Tags, then Send test. Email accepted shows the Current status: and Open the email and its timeline; recipients left out because they are blocked are listed. Under the form, The same email through the API shows it as cURL, Node and Python, ready to run with an app's key.

Test emails are real email: they count toward your daily limits like any other (Daily limits).

References

For developers, in English:

• REST API: authentication, sending, messages, blocked addresses, apps and keys, webhook deliveries.
• Webhooks: the events, the formats, the signature with code, retries and replay.
• Postmark compatibility: the /email endpoints and the Postmark webhook format.
• SendGrid compatibility: the /v3/mail/send endpoint, the Event Webhook and Inbound Parse.
• Mailgun compatibility: the /v3/{domain}/messages endpoints, Mailgun's webhooks and its routes' forwards.
• MCP server: the tools an AI agent uses.