Zapier and Groundmail
Send email from a Zap with the Webhooks by Zapier action, which makes a POST request to the Groundmail API. 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. A key in a Zap is visible to anyone who can edit the Zap, so a narrow key limits the damage if it leaks. See API keys.
- A Zapier account on a plan that includes Webhooks by Zapier, and a Zap with a trigger.
1. Add the action
- In the Zap editor, click the plus icon and choose Webhooks by Zapier.
- In the Event dropdown, choose POST, then continue.
- Fill in the action:
| Zapier field | Value |
|---|---|
| URL | https://api.groundmail.dev/emails |
| Payload Type | JSON |
| Data | One row per field, below |
| Headers | Authorization = Bearer gm_… |
Rows for Data (the key on the left, the value on the right; use fields from your trigger for the values):
| Key | Value |
|---|---|
from |
notifications@yourdomain.com |
to |
The recipient's email from your trigger |
subject |
Your subject line, with trigger fields if you like |
html |
The HTML body, for example <p>Hi {{name}}, your order shipped.</p> |
text |
A plain-text version of the same message |
from must be on a verified domain. At least one of html or text is required. Add reply_to, cc or bcc rows the same way; see Emails for every field.
To make a replayed Zap run harmless, add a second header, Idempotency-Key, set to a value from your trigger that is unique per event (an order id, for example). Groundmail returns the original response instead of sending twice for 24 hours. See Idempotency.
If you need the body to be exact JSON, or the API rejects the request as invalid, use the Custom Request event instead. It sends what you type without parsing it, so set the method to POST, add a Content-Type: application/json header next to the Authorization header, and paste the JSON body.
2. Test it
Click Test step. 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 test with 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 and produces a delivered event. To see what a failure looks like, use bounce@simulator.groundmail.dev. The full list is in Testing.
Check the result under Emails in the Groundmail dashboard. When you are done, replace the test key with a live key.
3. Know when mail bounces
The action returns once Groundmail accepts the message. To react to a bounce or a delivery, create a webhook and point it at a Catch Hook trigger in a second Zap:
curl -X POST https://api.groundmail.dev/webhooks \
-H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.zapier.com/hooks/catch/…",
"events": ["email.delivered", "email.bounced", "email.complained"]
}'Troubleshooting
401 unauthorized. The header must be Authorization with the value Bearer gm_…, including 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.
403 insufficient_scope. The key cannot send. Create a key with the Send only preset or emails:send.
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.
400 validation_error. A required field is missing or empty, to is not a valid address, or the JSON was malformed. The message and details in the response say which field. See Errors.
429. You hit a sending limit. See Sending limits.