# Capture replies by email Connect beel_email and BeeL. keeps a copy of the replies your customers send to the emails of your invoices. What changes in those emails and what is not captured. 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](/guides/connections), BeeL. also keeps a copy, and you can read it through the API and the [`invoice.reply.received`](/webhook-events/onInvoiceReplyReceived) webhook (see [Read customer replies](/guides/customer-replies)). ## Connect it ```bash 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](/guides/reply-permissions)). The company must have an `email`, which is where its replies keep arriving. Without it the call answers `422` [`CONNECTION_REPLY_TO_REQUIRED`](/errors/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`](/errors/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`](/errors/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](/guides/customer-replies#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 - [Connections](/guides/connections): the resource, the provider catalog and how to disconnect - [Read customer replies](/guides/customer-replies): webhook, list and detail - [Sending email](/guides/sending-email): how invoice emails are delivered --- Full OpenAPI spec: https://docs.beel.es/api/openapi