Mailhooks

Turning one on

Mailhooks are off for every table until someone turns one on. The switch is the Mailhooks tab in a table’s settings. Turning it on mints an address for that table alone — a long random name on a Ragextract mail domain, which the tab shows you and which you cannot guess or construct.

Copy it from the tab, forward an email to it, and a row appears on that table.

Set a monthly spend cap first if you have not already. A mailhook is the one part of Ragextract that spends credits when nobody is signed in, and a cap is the only limit measured in credits rather than in messages. It is not required and nothing will stop you — the tab says so if you have none. See how credits work.

Enabling a mailhook needs Manage on the workspace, and so does merely looking at the tab. That is stricter than most settings and deliberate on two counts: turning one on decides that people who are not signed in may write into the workspace, which is more than Read & Write means; and seeing the address is as good as having it, because the address is what grants the access. See sharing a workspace.

One address per table. A second table wanting mail gets its own mailhook and its own address — a mailhook delivers to a table, never to a workspace.

Who is allowed to send

Every mailhook carries a list of authorised senders, and mail from anywhere else is refused. When you turn one on the list starts with your own email address, so forwarding from your own mailbox works immediately and nothing else does.

The list is the security control, not the address. An email address cannot be kept secret in any useful sense — it travels in plaintext through every mail server that touches it and sits in the sender’s Sent folder for ever. So a mailhook is built on the assumption that its address will get out, and the thing standing between a leaked address and your credit balance is the list of people permitted to use it.

The consequence is worth stating before you meet it: a supplier emailing invoices straight in is something you have to allow deliberately. Add their address to the list and it works from the next message. Until you do, their mail is refused.

Three details that decide whether a match happens:

• It matches the address the mail genuinely came from, not the From line, which anyone can write. Before we see a message at all, it has had to prove it came from the domain it claims, and mail failing its own domain’s policy is refused before it reaches us. That is what makes a list of addresses worth having rather than decorative.
• An entry is one address, or a whole domain. Write ap@supplier.com for one person or @supplier.com to allow everyone there. A tagged address is a different address, though: ap+ragextract@supplier.com does not match ap@supplier.com.
• Consumer mail providers cannot be added as a domain. @gmail.com is not a narrower rule than “anybody”, so it is refused — add the exact address instead.

One limit of any such list is worth knowing rather than discovering: authentication happens at the level of a domain. Someone else inside a permitted sender’s own organisation may be able to send as them. That is that organisation’s mail hygiene rather than something Ragextract can see, and it is a reason to authorise the addresses you actually need and no more.

Forwarding rules

Forwarding by hand arrives as you, so it works from the moment you turn a mailhook on. An automatic forwarding rule is the case worth understanding, because forwarding is exactly the operation that changes who a message appears to be from.

Most business mail systems rewrite the sender as they forward, so that the message still passes the checks that stop forgery. Ragextract understands the common rewrite and reads your own address back out of it, which means your address on the list is usually enough — the same entry that was already there for forwarding by hand.

Some systems forward without rewriting, and the message arrives as the supplier instead. Then the supplier’s address is what the list needs. And a few rewrite in a way nothing can undo, which is what domain entries are for: allow @your-company.com and every rule forwarding from your own mail system is covered.

Rather than guess which of those your mail system does, set the rule up and read the activity list — it is under Advanced at the foot of the Mailhooks tab, closed until you open it. It shows the domain each message came from, and a refused one carries an Allow button that fills the entry in for you. That button is the only thing that will tell you which domain your forwarder rewrites to.

A mailhook never answers

Nothing comes back from a mailhook — not a confirmation, not a bounce, not a rejection. A message that produced four documents and a message sent to an address with a typo in it look exactly the same from your outbox: sent, and then silence.

That is deliberate. Any answer at all would be a problem: a reply to a forged sender sends mail to whoever was forged, a reply to an address that forwards into the mailhook loops, and an answer that explained why a message was refused would hand anyone probing the address your list of authorised senders, one message at a time. Silence is the only response that tells a stranger nothing, so it is the response everyone gets.

One exception, and it is a useful one. If you get a bounce saying the address doesn’t exist, that one is real — it means the message never reached Ragextract at all, so check the address itself. Silence means we received it. A failure notice means we did not.

Read the product instead. There are two places the truth is:

• The activity list in the Mailhooks tab, under Advanced — the last 25 messages, each with what happened to it, which domain it came from, and how many documents it produced. This is the authoritative answer, and it is collapsed by default because it is a diagnostic rather than a control.
• The table. An accepted message appears as a new row with its documents on it, within a couple of minutes.

A refusal in that list is almost always a sender that is not on the allowlist, and it comes with an Allow button that adds the domain it arrived from.

What one email becomes

One email is one row. Every attachment worth keeping becomes a document in the workspace, the group of them becomes an unnamed bundle, and that bundle backs a single new row on the table. The first attachment is the bundle’s primary document.

That shape is right for an invoice and its two annexes, and wrong for thirty unrelated CVs. If you want thirty rows, send thirty emails.

What happens next depends on the table:

• In an auto-mode table the row runs itself, and only once every attachment has finished being read — a row is never extracted against documents that are still ingesting.
• In a manual table the row waits for you, with its documents attached and nothing spent on answers.

Two edges worth knowing about:

• An email with nothing to ingest adds no row and costs nothing. A reply on a forwarded thread, or a message carrying only a signature, is accepted and quietly does nothing. It is not treated as an error, because it is not one.
• Past 15 attachments the row takes the first 15, which is the limit on any bundle. The rest are not lost — they are in the workspace files panel like any other document — they are simply not on that row.
• The same message twice makes one row, not two. If a forwarding rule loops, an automation gets stuck, or a mail server retries, the repeat is recognised, costs nothing and adds nothing. It shows in the activity list as a duplicate.

What is left out of a row

An email carries far more parts than the person sending it thinks. The rule Ragextract applies is keep what the message encloses, drop what the message displays: a signature logo, a social icon or a header image is drawn by the body of the email and is dropped, while a file the sender attached is kept — even when both of them are PNGs. A small image carried inline that nothing in the body refers to goes the same way, and so does anything outside the supported formats — a calendar invitation, most commonly.

Nothing that is dropped is read, so nothing that is dropped is charged. The rule is deliberately generous — it would rather keep a logo, which costs a credit, than lose an invoice, which costs you the document. If a row has fewer documents on it than the email had attachments, an ignored part is the usual explanation.

Subject lines and message bodies are never stored. Only the attachments become documents. What is kept about the message itself — who sent it, when, and whether it was accepted — is described in the privacy notice.

The size limit here belongs to email, not to your tier

One email can carry about 18 MB of attachments in total, and this is the one thing about mailhooks that catches people out, because for most paid tiers it is tighter than the account you have:

A Gold organisation entitled to 300 MB uploads gets about 18 MB by email, and no part of the product would otherwise tell it so. The limit is the mail system’s rather than ours — encoding an attachment for transport inflates it by about a third, and the message is refused above the ceiling before it reaches Ragextract at all, which means an oversized email produces no row, no error and no record. Large documents want uploading in the app.

Three limits you already have apply here unchanged:

• Your tier’s maximum size for a single file. One attachment over it is skipped and the rest of the email goes through — one bad part does not cost you the others.
• Your tier’s pages per document. An over-long attachment fails to ingest exactly as it would on upload, and is not charged. See tiers and limits.
• A cap on messages per hour, per mailhook. It sits far above any pattern of a person forwarding mail and exists so that a mailbox someone else has got into cannot run all night.

What it costs

The ordinary rates, with nothing added for the channel: one credit per page to read each attachment, and the column’s rate per cell if the table runs the row. See how credits work.

What is different is that nobody is present when it is spent. A mailhook on an auto-mode table turns other people’s email into extraction runs against your balance. That is the feature working — and it is the case where a monthly spend capearns its keep most. The cap is enforced at every debit, so topping up does not lift it, which is the whole point of it. Auto mode makes the same argument for the attended case; a mailhook is the unattended one.

Worth knowing what the ceiling would otherwise be. A single email can carry fifteen documents, and a row backed by more than three costs extra on every cell, so one message into a wide table can run to around a thousand credits. A mailhook accepts a bounded number of messages an hour, but that bound is counted in messages, not money — the cap is the only limit denominated in what you actually care about.

One cost is easy to miss: a row backed by more than three documents costs more per cell, and email produces multi-document rows by default rather than by choice. A six-attachment email into a wide table is materially dearer to extract than a one-attachment email, and nothing about the finished row shows it. Bundles explains the arithmetic.

Pausing, and rotating the address

The switch in the tab pauses a mailhook without destroying it: the address survives, and mail sent to it is discarded rather than turned into rows. As everywhere else, the sender is told nothing — a paused mailhook and a working one look identical from the outside, and the activity list is where a paused one is visible. Turning it back on resumes with the same address and the same list.

Rotate the address — the refresh button beside it — if it has travelled further than you meant it to. You get a new address immediately, the old one stops accepting mail, and your authorised senders come across with it, which is the point: rebuilding a list by hand is exactly the friction that stops people replacing an address they should replace. Everything already in the workspace stays where it is.

The one thing rotation cannot do is tell anyone. A mailbox rule or an address book pointing at the old address simply stops working, silently, so tell whoever was using it. There is no way to change an address in place — the address is the mailhook — so rotating always means a new one.

What it does not do

• It never replies. Not to confirm, not to explain a refusal, not to report a document that failed. Everything a mailhook has to say is in the app.
• It does not read the email. The subject and the body are not stored and never become an answer; only attachments become documents.
• It does not accept a whole domain. Every authorised sender is one address, added deliberately.
• It does not feed a workspace. A mailhook belongs to one table, and a document arriving through it lands on that table’s row.