Docs menu

Receive mail in your app

Use Flinkk Mail as the inbound side of any product: give each customer, branch or team its own address on your domain, and have every message delivered to your app as a webhook. Nothing here is tied to one kind of business.

The pieces

1. A domain with its inbound MX record verified (Domains in the app). 2. Receiving addresses, one per customer, branch or team, created by API when you create them in your own product. 3. A forwarding rule that posts each received message to your URL. 4. Optionally, contacts from CSV attachments and created addresses only.

Create an address for each customer

curl -X POST https://mail.flinkk.io/api/v1/addresses \
  -H "Authorization: Bearer $FLINKK_API_KEY" -H "Content-Type: application/json" \
  -d '{"local_part":"acme-london"}'

This creates acme-london@<your domain> (the domain of the API key) and is safe to repeat: an existing address is returned with "created": false. GET /api/v1/addresses lists them and DELETE /api/v1/addresses/{id} removes one.

Forward received mail to your app

Open Domains > your domain > Forwarding, or use the API:

curl -X POST https://mail.flinkk.io/api/v1/inbound-rules \
  -H "Authorization: Bearer $FLINKK_API_KEY" -H "Content-Type: application/json" \
  -d '{"match":"stays.example.com","url":"https://your-app.example.com/api/inbound-email","secret":"a-long-random-secret"}'

Field
`match`	A domain (`stays.example.com`) or a single address. Must be a domain in your workspace.
`url`	A public `https` address. Private and internal addresses are refused.
`secret`	At least 16 characters. Sent in the `x-inbound-secret` header (change the name with `header`). Stored encrypted and never shown again.
`add_contacts`	Add people with an email address in a CSV attachment to Contacts.
`contact_group`	Base name of the Contacts group. Each receiving address gets its own, such as `Guests - acme-london`.
`require_address`	Accept mail on the domain only for addresses you created. Everything else is dropped.
`active`	Pause a rule without deleting it.

Each message is posted as a raw email (Content-Type: message/rfc822) with the original recipient address, subject, body and attachments, so your app can tell which customer it was for from the address. Use Send test (or POST /api/v1/inbound-rules/{id}/test) to check the URL and secret before real mail arrives; a wrong secret is reported clearly.

Delivery is best effort with one retry. The message is always saved in Flinkk Mail first.

Contacts from CSV attachments

With add_contacts, the first CSV attachment's rows that have an email address are added to a Contacts group named after the receiving address. Columns are recognised by name (Email, Name or First name and Last name, Phone). People are added not subscribed to marketing, because receiving an address in a file is not consent. Sending the same file again does not add anyone twice. A file with no email column adds nobody.

Only accept mail for addresses you created

With require_address, random@stays.example.com is dropped unless you created it. This stops strangers filling a customer inbox and keeps one customer's mail from landing in another's.

On this page: The pieces · Create an address for each customer · Forward received mail to your app · Contacts from CSV attachments · Only accept mail for addresses you created