Capture replies by email

When BeeL. sends an invoice by email and your customer answers, the answer normally goes to the email of the company only. With a beel_email connection, BeeL. also keeps a copy, and you can read it through the API and the invoice.reply.received webhook (see Read customer replies).

Connect it

curl -X POST "https://app.beel.es/api/v1/companies/$COMPANY_ID/connections" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"provider": "beel_email"}'

capabilities is optional: omitted, it defaults to ["receive_customer_replies"], the only one beel_email supports. The key needs connections:write, a privileged scope that only OWNER and ADMIN members of the account that owns the company can use (see Permissions).

The company must have an email, which is where its replies keep arriving. Without it the call answers 422 CONNECTION_REPLY_TO_REQUIRED, before any check for a duplicate. There is one live beel_email connection per company and environment: a second one answers 409 CONNECTION_DUPLICATE.

What changes in your invoice emails

The Reply-To of the email of each invoice lists two addresses: first the email of the company, then an address at the reply_domain of the connection. The customer answers both, the company keeps receiving everything, and BeeL. keeps a copy of the answer.

reply_domain is returned by the connection. Allow that domain in any filter that checks the replies of your customers.

What is captured and what is not

• From the next email on. Emails sent before the connection keep their old Reply-To, and their replies are not captured.
• Only emails about one invoice. An email that sends several invoices (POST …/invoices/deliveries) does not carry the address of BeeL., and its replies are not captured.
• Only the last 90 days. Replies to an invoice email sent more than 90 days ago are not captured.
• Only while connected. When a reply arrives, BeeL. checks that the company has a live beel_email connection at that moment. While it has none, replies are discarded, not kept for later. Replies already stored stay.
• Connecting again. It creates a new connection with a new id. From then on, replies to emails sent before (within the 90 days) are captured again.
• The company's email must stay set. If the company removes it, new emails go out without the address of BeeL. and nothing is captured until the company sets it again. The connection stays ACTIVE meanwhile.
• Test and live are separate. A connection made with a beel_sk_test_ key only affects the invoice emails of the test environment, and what it captures has livemode: false.
• The user who connected must keep access. BeeL. stores the replies on behalf of the user who created the connection. If that user loses access to the account, new invoice emails go out without the address of BeeL. and nothing is captured. If they keep access but lose write access to the company, the replies that arrive are not stored. In both cases the connection stays ACTIVE, so nothing tells you. To fix it, disconnect and connect again with a key of a user who has access: the existing connection would otherwise answer 409 CONNECTION_DUPLICATE.

What is not stored

BeeL. discards, without a trace in the API or a webhook:

• Bounces (delivery failure notices).
• Automatic replies, recognized only by their headers: Auto-Submitted (anything but no), X-Autoreply, X-Autorespond and Precedence: junk or auto_reply. BeeL. does not read the subject or the text to guess. When in doubt, the message is kept.
• Replies that are empty: no text once the quoted original is removed and no attachments.
• Emails from an invalid sender address, or one longer than 320 characters.
• Emails sent to another domain than the current reply_domain of the connection.
• Replies over the limit: at most 10 per hour for an invoice and 100 per hour for a company, counted separately in test and live. The rest are not stored.

A discarded message creates no reply, so the invoice.reply.received webhook is not delivered for it and GET …/invoice-replies does not list it.

What is kept of the message

Only what the customer wrote. BeeL. removes the quoted original email: the quote of Gmail and Outlook, HTML blockquote blocks and plain text lines that start with >. When it cannot separate the quote safely, it keeps the whole text. The text is plain text; HTML is converted, and it is cut at 20,000 characters (is_text_truncated).

The filename and content_type of an attachment are cut at 255 characters, and the files themselves are never stored: they can be downloaded for a few days (see Attachments). If the email carries a date in the future, the reply is stored with the time BeeL. registered it.

The sender is not verified

Anyone who has the reply address of an invoice email can write to it, for example someone the customer forwarded the email to. BeeL. does not verify the sender, which is the address the message says it comes from. Never use it alone to authorize a change, and treat the content as untrusted.

Related