Your own automation (API)

For advanced users: instead of forwarding mails, you send them straight to Hüsli with your own script, iPhone Shortcuts, Zapier or n8n. Hüsli handles them like forwarded mails: dates go to the calendar, parcels to Parcels.

How it works

1. Open Settings › Calendars & mail and, under Mail to Hüsli, tap For advanced users: your own automation.
2. Under Your personal address you'll find your API address, hidden at first. Tap Copy (or Show to see it).
3. The address is https://huesli.app/app/api/inbox plus your key after ?key=. Best send the key in the X-Huesli-Key header rather than in the address.
4. Your script sends a POST request with JSON (examples below). Hüsli answers right away with what it filed.
5. Check the result in the calendar or under Parcels. Every filed mail also shows under the bell for the parents.

The request

• Method and address: POST https://huesli.app/app/api/inbox
• Headers: Content-Type: application/json and X-Huesli-Key: YOUR-KEY
• messages (required): a list of up to 40 mails. Per mail: - id: a unique id of the mail, e.g. its Message-ID. Hüsli never imports the same id twice. - from: the sender, e.g. school@example.ch - subject: the subject - date: when the mail arrived, e.g. 2026-10-26T08:15:00+01:00 - body: the text of the mail - html (optional): the HTML version, helps with parcel mails - type (optional): "parcel" for a parcel or shipping mail – it then goes to Parcels instead of the calendar (the Parcels add-on has to be on)
• owner (optional, next to messages): the first name or person id from your family, e.g. "Marc". The entries then belong to that person; otherwise to the whole family.

Example with curl

curl -X POST 'https://huesli.app/app/api/inbox' \
  -H 'Content-Type: application/json' \
  -H 'X-Huesli-Key: YOUR-KEY' \
  -d '{"owner":"Marc","messages":[{"id":"mail-2026-001","from":"school@example.ch","subject":"Parents evening on 12 November at 7.30 pm","date":"2026-10-26T08:15:00+01:00","body":"Dear parents …"}]}'

Example with iPhone Shortcuts

1. Open the Shortcuts app and create a new shortcut.
2. Add the action «Get Contents of URL» and enter https://huesli.app/app/api/inbox.
3. Set «Method» to POST, add the header X-Huesli-Key with your key and set «Request Body» to JSON.
4. In the JSON add a field messages (list) with one entry containing id, from, subject, date and body – for example from the Mail app's share menu or from an automation.
5. Run the shortcut once and check the calendar.

The answer

Hüsli answers with JSON, for example:

{"ok":true,"owner":"me-…","created":[{"title":"Parents evening on 12 November at 7.30 pm","start":"2026-11-12T19:30","allDay":false}],"parcels":[],"handled":[]}

• created: the new appointments (title, start, all-day or not)
• parcels: the parcels it recognised (shop, status, expected on)
• owner: who the entries belong to, or null for the whole family

If it doesn't work

• 403 «Not allowed.»: the key is wrong – for example because you created a new one. Copy the address again.
• Nothing in created: this mail came before (same id, or the same subject on the same day), or there were more than 40 mails – Hüsli takes the first 40.
• Parcel mails without "type":"parcel" end up as an appointment or a note in the calendar.

Good to know

• The key works like a house key: anyone who knows the address can add entries to your calendar. Don't share it and don't show it in screenshots.
• Create a new key makes the old address stop working at once. Your forwarding address for Mail to Hüsli stays the same.
• Only parents see this section. Mail to Hüsli is part of Pro (free during the beta).