Emails and notifications
Send one email to a contact from your organization, or tell your own team that something happened on your website.
Two endpoints send email for your website, to two different audiences:
| You want to | Use | Who gets it |
|---|---|---|
| Email the person who filled in your form: "We got your request", "Your quote is on its way" | POST /v1/emails | One contact |
| Tell your team: "New wholesale inquiry", "New job application" | POST /v1/notifications | Every member of your organization |
Both take plain text, both need an idempotency key, and both are rate limited to 200 calls an hour.
Email a contact
POST /v1/emails sends one transactional email to one contact. The contact is saved first, the same way as PUT /v1/contacts, and the email is recorded on their timeline in the CRM.
curl -X POST https://api.lahuta.org/v1/emails \
-H "X-Api-Key: $LAHUTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "commission-ack:2291",
"contact": {
"kind": "person",
"firstName": "Hannah",
"lastName": "Lindqvist",
"emails": [{ "label": null, "value": "hannah.l@example.com" }]
},
"subject": "We got your dinnerware request",
"body": "Hi Hannah,\n\nThanks for your request for a set of eight plates. Tomás will look at your reference photos and send a quote within three days.\n\nNorthside Pottery",
"replyTo": "studio@northsidepottery.com"
}'{
"emailId": "0197b36a-4e28-7c90-8b15-2d7f3a1e6c49",
"contactId": "0197b36a-4e11-7a53-9f02-6b1c8e4d2a37",
"opened": true
}| Field | Required | What it does |
|---|---|---|
key | Yes | Your name for this email. Sending it again sends nothing and returns "opened": false. See Idempotency |
contact | Yes | Who it's for. The email goes to the first address in emails, and to nobody else |
subject | Yes | One line, up to 200 characters |
body | Yes | Plain text, up to 20,000 characters. Blank lines become paragraphs |
replyTo | No | Where replies should go |
Things to know:
- It's sent as written. The body is plain text. HTML tags show up as text, not formatting. There are no merge tags, so put the person's name in yourself.
- It comes from your organization. The email goes out under your organization's name from its Lahuta address. That's true even if you've connected your own mailbox under Settings → Email, so receipts and confirmations always arrive quickly.
- Bounced addresses are skipped. An address that bounced before, or marked your email as spam, isn't emailed again.
- It's for one person at a time. To reach your whole list, use a campaign or your newsletter.
If the contact has no email address, you get 422 with {"_tag":"NoAddress"} and nothing is sent.
Notify your team
POST /v1/notifications tells everyone in your organization that something happened on your site. Use it for form submissions your team should act on.
curl -X POST https://api.lahuta.org/v1/notifications \
-H "X-Api-Key: $LAHUTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "commission-request:2291",
"subject": "New dinnerware commission request",
"body": "Hannah Lindqvist wants a set of eight plates in a matte white glaze.\n\nBudget: around $400",
"url": "https://lahuta.org/dash/northside-pottery/crm/groups/0197b2e5-0c4a-7d11-a2f3-6e8b9c1d0a47"
}'{ "notified": 3 }| Field | Required | What it does |
|---|---|---|
key | Yes | Your name for this notification. Sending it again notifies nobody twice |
subject | Yes | One line, up to 200 characters. It's the email's subject and heading |
body | Yes | Plain text, up to 20,000 characters |
url | No | Adds an Open button to the email that goes to this link, for example the group or contact in your dashboard |
notified is the number of members in your organization.
Each member gets an email headed From your website, with your subject and body. Members who've turned off Submissions under Settings → Notifications don't get the email. Your customers never see these.
Put it together
A typical form handler on your site does three things with one submission id:
- Save the person and their answers with
PUT /v1/contactsorPUT /v1/groups. - Email them a confirmation with
POST /v1/emails. - Tell your team with
POST /v1/notifications.
Build each key from the submission id, like commission-ack:2291 and commission-request:2291. Then a retried form never sends anything twice.
Errors
| Error | When |
|---|---|
422 NoAddress | POST /v1/emails only: the contact has no email address |
429 TooManyRequests | More than 200 emails, or 200 notifications, this hour. Wait retryAfterSeconds |
400 | The subject has a line break or is too long, the body is empty, or url isn't a valid link |
See Emails and Notifications in the API reference.