GroundmailDocs

Make and Groundmail

Send email from a Make scenario with the HTTP app's Make a request module, which calls the Groundmail API directly. No Groundmail app is needed.

Prerequisites

  • A Groundmail account with a verified sending domain.
  • A Groundmail API key. Create one under API Keys in the dashboard. Choose Send only, and limit it to your sending domain with the allowed domains option. See API keys.
  • A Make scenario with a trigger or any module that produces the recipient's email address.

1. Add the module

  1. In your scenario, add a module and choose the HTTP app, then Make a request.
  2. Fill in the module:
Make field Value
URL https://api.groundmail.dev/emails
Method POST
Authentication type API key
Body content type application/JSON
Body input method JSON string
Parse response Yes
Return error if HTTP request fails Yes

  1. For Credentials, create a new API key credential. Put the key in the header, name the parameter Authorization, and enter Bearer gm_… as the key (the word Bearer, a space, then your Groundmail key). Make's documentation recommends using the credentials field rather than defining authentication in the request headers.

    If you would rather set it by hand, leave Authentication type as No authentication and add an Authorization: Bearer gm_… entry in Headers.

  2. Enter the JSON body, mapping values from earlier modules where you need them:

{
  "from": "notifications@yourdomain.com",
  "to": "{{1.email}}",
  "subject": "Your order has shipped",
  "html": "<p>Hi {{1.name}}, your order is on its way.</p>",
  "text": "Hi {{1.name}}, your order is on its way."
}

{{1.email}} and {{1.name}} are placeholders for fields from module 1; pick yours with Make's mapping panel. from must be on a verified domain, and at least one of html or text is required. See Emails for every field.

To make a re-run harmless, add an Idempotency-Key header with a value that is unique per event (an order id, for example). Groundmail returns the original response instead of sending twice for 24 hours. See Idempotency.

2. Test it

Run the module once. With a test key (gm_test_…, created by ticking Test key on the API Keys page), Groundmail runs the whole pipeline but delivers nothing, so you can use any recipient. A successful response looks like this:

{ "id": "msg_…", "status": "sent", "test": true }

You can also use a live key and send to delivered@simulator.groundmail.dev, which never reaches a real inbox. Use bounce@simulator.groundmail.dev to see a hard bounce. The full list is in Testing. The email appears under Emails in the Groundmail dashboard. When you are done, replace the test key with a live key.

3. Handle failures in the scenario

With Return error if HTTP request fails set to Yes, the scenario stops on a 4xx or 5xx response, and the response body explains why. Groundmail errors are JSON with a stable code and a hint; see Errors. To react to a bounce or complaint after Groundmail accepted the message, create a webhook that points to a Make custom webhook URL.

Troubleshooting

401 unauthorized. The Authorization value must be Bearer gm_…, with the word Bearer and a space. Check the key is active on the API Keys page.

403 forbidden. The domain in from is not verified on your account, or the account is still on the sandbox sender, which only sends to your own account email. Verify the domain under Domains. A 403 domain_not_allowed means the key is limited to other domains, and insufficient_scope means the key cannot send.

400 validation_error. A required field is missing, to is not a valid address, or the JSON string is malformed (an unescaped quote in a mapped value is the usual cause). The message and details say which field.

422 validation_error with suppressed. Every recipient is on your suppression list or was held back as unable to receive mail. Do not retry the same address; see Suppressions.

429. You hit a sending limit. See Sending limits.