Skip to content
Guides

Forward invoices by email

Some services have no API ShipVitals can read: a VPS host, a domain registrar, a small SaaS. Forward their invoices to your workspace's invoice address and each one becomes a cost line on the project it belongs to, in place of an estimate. Owners and admins use the invoice inbox. This guide covers finding the address, forwarding from Gmail and other mail, confirming who may send, and reviewing what arrives.

Find your invoice address

  1. In the sidebar, choose Connections (on a phone, More → Connections), or press g then c.
  2. Open All services. After the services, under Entered by hand, or sent by you, choose Invoices by email ("Bills you forward, as cost lines.").

A service's Not yet page leads here too: "Today: forward …'s invoices." with a link to Invoices by email.

The page says Invoices by email, "For services with no API, forwarded invoices become cost lines." Under Your invoice address is your workspace's own address, like bills+k7w2abcd2345@in.shipvitals.com, with Copy the address, and three steps:

  1. "Copy the address."
  2. "In Gmail, add it as a forwarding address." with Open Gmail's forwarding settings.
  3. "Create a filter for invoices from the senders you choose." with Open Gmail's filters.

Back to Connections returns to Connections.

Forward from Gmail

  1. Press Copy the address.
  2. Press Open Gmail's forwarding settings. In Gmail, press Add a forwarding address, paste the address, and go on.
  3. Gmail sends a confirmation code to the new address. Go back to Invoices by email (reload the page if the code isn't there yet). Once the code arrives, the card says "Gmail sent a confirmation code: 492018. Enter it in Gmail to finish." (with your code).
  4. Enter the code in Gmail's forwarding settings and press Verify.
  5. Press Open Gmail's filters and create a filter for your invoices, for example from billing@hetzner.com. Choose Forward it to and pick your invoice address.

Forward only the senders whose bills you want: every mail that arrives is kept for review. ShipVitals takes the code only from a mail Google signed, so a mail that pretends to be Gmail's can't put a code on the card.

Forward from other mail

Any mail service or client with an automatic forwarding or redirect rule works: point the rule for each vendor's invoices at your invoice address. ShipVitals reads a PDF, or a PNG or JPEG image, attached to the mail, or the mail's own text when the bill is in its body.

The sender is whoever the mail is from when it reaches ShipVitals. An automatic forward keeps the vendor as the sender. If you forward a bill by hand, it arrives from your own address, and that is the sender you confirm.

Confirm a new sender

Nothing from a new sender is read until you confirm it, so a mail nobody asked for can't add costs or spend anything on reading.

  1. Open Invoices by email. The bill is in the Inbox list with the sender's address and "Received …".
  2. It says "A new sender: nothing is read until you confirm it, so a mail nobody asked for can't add costs."
  3. Press Confirm sender if you expected it. ShipVitals reads this bill, and every later bill from the sender is read as it arrives. Or press Not an invoice (see What happens to non-invoices).

While a bill is being read, its row says "Reading the invoice…".

The "Invoice needs a look" email

When a bill arrives that waits for you (a new sender's, or one marked Sender not verified), owners and admins get an email, "A new sender's invoice is waiting", headed "An invoice needs a look". It names the sender and, when there are more, how many bills are waiting. Open the invoice inbox opens the page. It comes at most once a day.

Sender not verified

ShipVitals checks that each mail is signed (DKIM) by the domain in its From address. A bill that isn't is marked Sender not verified, even from a confirmed sender, and waits: "This mail isn't signed by its sender's domain, so it waits for you. Read it only if you expected it."

  • Press Read it to read that one bill.
  • Or press Not an invoice.

A new sender's unsigned bill shows Sender not verified as well as the new-sender line. Confirm sender confirms the sender but doesn't read that bill: the row then offers Read it.

Review a bill

Once read, a bill's row shows the vendor, the amount (with "incl. … tax" when it has tax), the sender, when it arrived and the period it covers, and how sure the reading is: "Read with high confidence", or "Check the fields: read with low confidence". Open the invoice opens the PDF or image that came with it.

  1. Check the vendor, period and amount against Open the invoice.
  2. If something is wrong or missing ("Still needed: period, amount."), press Edit. Fill in Vendor, Currency (three letters, such as USD), Period from, Period to, Total, tax included, Tax (optional) and Project, then press Save (or Cancel).
  3. Under Project, choose the project the bill belongs to. Until you do, it says Choose a project.
  4. Press Confirm. It's off until nothing is still needed and a project is chosen.

The row then says "Confirmed: a cost line on …" with the project.

If a field is wrong, Save says "Check the fields: the amount is a number, like 12.50." or "The period ends before it starts."

When a bill couldn't be read, its row says why and leaves the fields to you, for example "This PDF has no text to read (it may be a scan). Fill in the fields with Edit." Use Edit as above.

Always assign a sender to a project

The first time you confirm a bill from a sender, ShipVitals asks once, for example "Always assign Hetzner invoices to smart-home?"

  • Yes, always: later bills from the sender go to that project.
  • No, I'll choose: you pick the project on each bill.

With Yes, always, a later bill from that sender confirms itself when it's signed by the sender's domain, read with high confidence and nothing is missing. Anything else waits for you to Confirm.

How a bill becomes a cost

A confirmed bill is a cost line on its project, in the bill's period. On the Costs tab its Source is INV, "From an invoice" (see Costs and budgets).

When ShipVitals knows the vendor as a service it estimates (from the vendor's own domain or name), the bill replaces that service's estimate (EST) for the same month, so the cost isn't counted twice. Otherwise it's a line of its own under the vendor's name.

What happens to non-invoices

Press Not an invoice on any bill that isn't one: a newsletter, a receipt you don't want counted, a mail sent by mistake. Its row says "Not an invoice · removed on …", and 7 days later it's deleted with its file. A confirmed bill can't be marked Not an invoice.

When reading shows a mail isn't a bill, ShipVitals marks it Not an invoice itself.

A mail with nothing in it that could be a bill doesn't appear at all.

Limits

  • The Inbox lists the last 90 days, 50 bills at a time: Show more loads the next ones.
  • A workspace keeps up to 200 mails a day, and 50 from one sender. Mail over that isn't kept.
  • ShipVitals reads up to 50 bills a day, and 10 from one sender. Past that, a bill says "Today's limit for reading invoices automatically is reached. Fill in the fields with Edit."
  • A mail can be up to 25 MB, with up to 20 attachments of 15 MB each.
  • An image over 5 MB isn't read automatically; fill it in with Edit.
  • Reading bills isn't charged to your AI credits.

For how forwarded mail is checked and stored, see /security and the Privacy Policy's invoice inbox section.