Log invoices that arrive in Gmail to a Google Sheet
Build a Kovca workflow that starts from a new Gmail message, copies the invoice fields the body states, and appends a Google Sheets row when those fields pass the checks you write.
Vendor invoices and bills land in a shared billing@ or ap@ Gmail inbox next to receipts, statements, reminders, and other mail. Someone opens each message and types the vendor, the invoice number, the invoice date, the due date, the currency, and the total into a spreadsheet. A resend or a reminder sometimes becomes a second row. A missing field shows up late.
This guide builds a workflow that starts when a new message arrives, copies those six fields from the subject and the body when the email states them, and checks the copy. A record whose status is valid is looked up in the invoice-number column, then appended as a new row, and the message gets a logged label. Any other status gets a check label and no new row. You'll start from a template, test it, and activate it on the Gmail and Google Sheets accounts.
The template already uses the Gmail New email trigger, Google Sheets Look up a row, Google Sheets Append rows, and Gmail Add label twice. It does not store a Gmail or Google Sheets account. You choose the accounts when you activate. Until then the draft saves, and Studio tests simulate the Gmail and Sheets steps.
Invoice Intelligence checks a structured invoice you already have: a number, a vendor name, a currency code, and at least one line with a description, a quantity, and a unit price. It returns status (matched, discrepancies_found, requires_review, or insufficient_information) and recommended_action. With no purchase order it returns insufficient_information, request_information, and missing_information containing purchase_order. It does not read an email, and it does not return a vendor, an invoice number, or a total copied out of free text. This workflow uses Extract data for the copy and Data Quality Intelligence for the check. Teams that already have the invoice as data, and a purchase order to match, can continue with Check vendor invoices against the purchase order before payment.
Look up a row searches the invoice-number column before the append. Its catalog output is ok and result. The sample result is {}, and the catalog does not name a field inside result that means the number was found. This template does not add a condition on result, and it does not treat {} as a match or as a miss. A resend can still append a second row. After a test on a sheet you control shows you which field means another row, add a condition on that field and move Append row to the not-found branch. Check new Google Sheets rows for data problems says the same thing about this action.
If the inbox only gets a few invoices a week, a Gmail filter on subject:(invoice OR bill) and a person who types the row is less machinery than this. A filter does not copy the six fields out of the body. A mail-parser product that writes a sheet is another way to do the typing. The workflow is for the inbox where someone is already opening each message to fill the sheet.
What you'll build
Send real requests is off. The run returned 200 and used 6 credits, with 916 Generative AI tokens. status is valid, log_it is true, lookup, append, and logged are marked sample, hold is skipped, and checked is null.
The false branch goes to Label check, then Result. invalid, warnings, and requires_review all take that branch. They do not look up a row, and they do not append one.
Watch the test
Watch the Studio test (MP4). It is a recording of the production Studio at kovca.io, in light mode, 17 seconds. The frame is the Test panel. Nothing in the recording is sped up. No Gmail or Google account is connected, and Send real requests stays off. Look up, Append row, and Label logged return their samples and are marked sample. That is not a row found in a sheet, not a row written to a sheet, and not a label applied in Gmail. Label check is skipped.
Studio test. Send real requests is off. Status 200. 6 credits. 916 Generative AI tokens. lookup, append, and logged are marked sample. hold is skipped. The output shows the extracted fields, status valid, and lookup_result.
The recording follows these steps:
- The Test tab is open. The input is the Harbor Paper invoice: subject "Invoice INV-1042 from Harbor Paper", body stating vendor Harbor Paper Co., invoice date 2026-03-02, due date 2026-03-30, currency USD, and total 1280.00, from
accounts@harborpaper.example.com. The input says Valid. Send real requests is off. The switch's own text says action steps return their sample result and nothing is sent. - Run test. The panel says the previous result is cleared until this one finishes.
- The status is 200. The panel on this recording showed 6 credits used (1 Decision AI evaluation) and 916 Generative AI tokens.
- Extract succeeded. Check fields succeeded and is marked Decision AI.
log_itsucceeded. Look up, Append row, and Label logged succeeded and are marked sample. Label check (hold) is skipped. The output lists the extracted fields,statusvalid, andlookup_result. That result stays on screen through the end of the recording.
That is one live Studio test of that email. Extract returned Harbor Paper Co., INV-1042, 2026-03-02, 2026-03-30, USD, and 1280.00. Check fields returned valid, with no issues. log_it is true. lookup_result is {}, which is the sample, not a row from a spreadsheet. appended and logged are true because those samples say ok: true. checked is null because Label check did not run. What Extract data returns on another message depends on that message.
The JSON later in this guide is the template's unit test for the same input when the test does not read the message. Every extracted field is absent, the status is invalid, and Label check is the only action that runs.
Build it in the Studio
1Start from the template
Click Use this template above, or open Gmail invoice log in Workflows.
The draft opens on the canvas. The components library is on the left. Triggers, AI, Action in an app, Data transformation, Flow, Core, and Human review are the groups. This workflow uses Gmail and Google Sheets, so both are under Triggers and under Action in an app once the draft uses them. Apps you have not connected, and that this workflow does not use, stay behind Connect another app. The pictures below are the production Studio, in light mode, with no Gmail or Google account connected. The template's step titles are the ones in the table above. The last card on the canvas is Result.
A close view of Label check. The false handle of the condition reaches it. The card says Gmail: Add label and shows a warning, because no Gmail account is connected.
Triggers. Gmail is listed because the draft starts from New email. Connect another app is under the list.
Add label is in the Gmail action list. No Gmail account is connected.
Look up a row and Append rows are in the Google Sheets action list. No Google account is connected.
2The workflow starts from a new email
Select the input step. It is Gmail: New email, not an API request. The account line asks you to connect Gmail. Leave it empty while you test.
Only emails matching is to:billing@example.com subject:(invoice OR bill), fully visible. In label says Connect Gmail to choose a label. Apply settings is under that.
to:billing@example.com subject:(invoice OR bill) is a stand-in. Replace it with the search you actually want. The field's description is "Advanced Gmail search using the same syntax as Gmail's search box." A live message that does not match that search does not start a run. The Test tab and an API call send the event you provide, so they still run when the search would not have matched. The reminder example in the template has the subject "Reminder: outstanding balance", which this search would not start.
In label filters by a single label id. Until an account is connected, the field says to connect Gmail to choose a label. The template leaves it unset.
The trigger description says it fires when a new message is received in Gmail. The same message does not start two runs: the event id is message_id. A later message is a new event and runs again.
Event fields later steps read:
The event also includes received_at, labels, thread_id, and to. labels is a list of label ids already on the message. The trigger's sample uses INBOX and UNREAD. This workflow does not read that list. from is a string, the sender as Gmail reports it. A manual run or an API call can omit fields the steps don't read.
body_text accepts at most 8,000 characters. Extract's instructions, with the subject, the sender, and the body filled in, can be at most 60,000 characters of workflow data. A body at the event's own limit stays under that.
3Copy the fields the email states
Select Extract. It is the Extract data node. The instructions name the six fields. The returns format is Fields (structured data).
The six fields are vendor, invoice_number, invoice_date, due_date, currency, and total. Each description says what to copy from the email. None of them is marked required.
The instructions say to copy only what the email states, to leave a field out when it does not state that field, and not to invent a number, a date, or a total. They ask for invoice_date and due_date as YYYY-MM-DD when the email states that date, for currency as the code the email states, and for total as digits and a decimal point with no currency symbol. The subject, the sender, and the body are inserted as {{input.subject}}, {{input.from}}, and {{input.body_text}}.
None of the fields is required on this step. A field the email does not state is left out. Later steps see that as absent.
Model settings stays closed. The template does not set a tier, a creativity, a maximum length, or a reasoning level. The step therefore uses the Extract data defaults: Fast, which that menu marks recommended, Precise, Medium, and Standard.
4Check the copied fields
Select Check fields. It is Data Quality Intelligence. record_type is the fixed value vendor_invoice. record is nodes.extract.output, the object Extract returned. fields is a fixed value, the rules below. rules, expected_relationships, and context are unset.
record_type is the fixed value vendor_invoice. record is nodes.extract.output. The fields box shows the start of the list. rules, expected_relationships, and context are not set. The last test returned status valid.
A required path that is missing or blank is missing_required_value, and the status is invalid. invoice_date and due_date must be ISO 8601 dates (YYYY-MM-DD is that shape). Anything else on those two paths is invalid_format, and the status is invalid. vendor, currency, and total are strings. A total such as 1280.00 passes the string rule. A date written as March 2, 2026 does not pass the date rule.
The node can also return warnings or requires_review when a value looks inconsistent with the rest of the record. This template logs a row only for valid. warnings and requires_review take the check label, the same as invalid.
5Decide whether to log the row
Select Log it?. A condition continues on true when every rule matches. This one has one rule.
Continue on true when all rules match. nodes.check.output.status equals valid.
The step's id is log_it. The output field log_it is that step's result: true or false.
6Look up the invoice number
Look up runs only on the true branch. It is Google Sheets' Look up a row action.
If it fails is Stop the run. Find is nodes.extract.output.invoice_number. Range is Invoices!A:A. Case sensitive is Not set. The spreadsheet id is the stand-in, and the whole id is in the field.
The spreadsheet id is a stand-in, the same kind of placeholder as the label ids. Replace it with the id from your sheet's URL. Range is the invoice-number column, so the first cell of the appended row is the invoice number. The field's description says a bare sheet name is not a range. Invoices!A:A is a column range. Sheet names with spaces need single quotes.
The action finds the first row in that range, or on the first sheet if the range is empty, whose cell matches the query after Unicode and invisible-character normalization. Matching is case-insensitive and trims surrounding whitespace unless you set Case sensitive. The template leaves that unset.
If it fails is Stop the run. The step is safe to retry: repeating a lookup has no further effect, and a transient failure can be tried again within the run. If the lookup does not succeed, the run stops and Append row does not run. Choose the Google Sheets account on this step before you activate. In a Studio test, with Send real requests off, the step returns its sample and is marked sample. The sample is ok: true and result: {}.
That sample is not a row from your sheet. The catalog does not name fields inside result. This template reads result only to return it. It does not branch on it.
7Append the row
Sheet row builds one JSON row. The cells, in order, are the invoice number, the vendor, the invoice date, the due date, the currency, the total, and message_id.
The template is one JSON row: invoice number, vendor, invoice date, due date, currency, total, and message_id.
Each cell is a JSON string ({{json …}}). A quote, a backslash, or a line break in the invoice number, the vendor, a date, the currency, the total, or the message id stays in the cell. Row values parses that text into JSON. Append rows needs an array of rows.
Append row is Google Sheets' Append rows action.
If it fails is Stop the run. Range is Invoices!A1. Rows is nodes.rows.output.result. Value input is RAW. The spreadsheet id is the same stand-in, and the whole id is in the field.
range and value_input_option are required. The label names RAW and USER_ENTERED. The template uses RAW. The range locates the table to append to. Create an Invoices tab, or change both ranges to a tab you have. Put the invoice number in column A if you want Look up to search the same column the new row writes.
If it fails is Stop the run. Append rows is not idempotent: it is attempted once, and Kovca does not retry it. A second run with a new idempotency key can append another row. In a Studio test the step returns its sample and is marked sample. The sample is ok: true and result: {}. That is not a row written to a spreadsheet.
Label logged runs after a successful append.
Label_logged is a stand-in. It is not a label id from a mailbox. Add label's own description of the field is "Label IDs to add (IDs, not display names)." Replace it with the id of the label you want, such as the id Gmail assigns to a label you named Invoices/Logged. Once an account is connected, In label on the trigger lists the mailbox's labels.
If it fails is Continue (output.ok is false). A failed label does not undo the row, and it does not fail the run. The step is safe to retry. In a Studio test it returns its sample, ok: true, and is marked sample.
8Label the messages that are not logged
Label check is the false branch of Log it?.
If it fails is Continue (output.ok is false). Message ID is input.message_id. Label IDs is the fixed value Label_check. The last test is skipped, reason branch not taken.
Label_check is a stand-in, the same kind of placeholder as Label_logged. Replace it with the id of the label you want, such as the id behind a name like Invoices/Check.
If it fails is Continue (output.ok is false). The step is safe to retry. In a Studio test it returns its sample and is marked sample. That is not a label applied in your mailbox.
9Test it
Open the Test tab. Invoice INV-1042 and Payment reminder are the template's examples. Sample new email is the trigger's own sample, which is an invitation, not one of these messages. Leave Send real requests off.
The pictures' Test tab shows the Harbor Paper invoice pasted in. It also shows Sample new email and Recent from Gmail. It does not show buttons named Invoice INV-1042 and Payment reminder: those names are saved with the template, and they are listed when you open the template.
The input is valid. Sample new email and Recent from Gmail are the trigger's buttons. Send real requests is off. The subject is Invoice INV-1042 from Harbor Paper.
The unit test does not read the email. Extract returns no fields, every required path is missing, the status is invalid, and log_it is false. That is the JSON in the next section. A live Studio test reads the message. A valid result takes Look up, and with Send real requests off that step returns result: {} and is marked sample, then Append row and Label logged return their samples too. {} on Look up is still not a row found in a sheet, and the append sample is still not a row written there.
Before you activate, run messages you have actually seen, including ones that state every field and ones that do not. When the routes look right, turn on Send real requests once, with both accounts chosen and the stand-in ids replaced, on a message where an extra row and an extra label are harmless. Look at lookup_result on that run before you rely on it to mean "already logged."
Publish, call it, and activate it
The same workflow can be called over the API. The body uses the trigger's field names. Create an API key under API keys and keep it on your backend.
That curl calls a published workflow. On a valid result it runs Look up a row, Append rows, and Add label for real. On any other status it runs the check label for real. The steps need the Google Sheets account on Look up and on Append row, and the Gmail account on the label that runs. If an account is missing, the action fails. With If it fails set to stop on Look up and on Append row, a failed lookup stops the run and the row is not appended. A published call does not return the sample you see with Send real requests off.
The JSON below is the output this template's unit test expects for the Harbor Paper invoice when the test does not read the message. Extract returns no fields. Check fields reports each required path missing. Label check is simulated. Look up, Sheet row, Row values, Append row, and Label logged are skipped. This is not a response from a published API call.
The JSON above leaves out credits. A succeeded execute response includes that field. This example is the simulated run, so Label check is not charged. credits for an API call of this shape is 6 plus Extract data: 5 for Check fields and 1 for the API run. Extract data is at least 1 credit more, by tokens. The Studio test does not charge the run fee.
Look up the run later. This returns status, timing, and steps. It does not return the output. Keep the execute response if you need the fields or the status. Runs are kept for 30 days.
18f0a1b2c3d4e5c1 is a key you choose. The message id is a natural one. Keys are kept for 24 hours. A retry with the same key and the same request returns the original run instead of appending again. A new key can append again. Add label can be repeated without a second effect. Append rows cannot: a later run whose status is valid appends another row. Kovca does not store the message or the output.
To run it from Gmail, open Activate. The checklist is what's left: connect Gmail, connect Google Sheets, and, once an account is connected, choose that account on the trigger, on Look up, on Append row, on Label logged, and on Label check. It says up to 19 credits per event, plus Generative AI by tokens. The activate row is Publish and activate: run on every new email. The button on that row says Publish & activate. That publishes the draft and starts it. A live automation runs that pinned version. Later edits don't reach it until you publish them to the automation.
Connect Gmail and Connect Google Sheets are still to do. Tested is checked. Up to 19 credits per event, plus Generative AI by tokens. Publish and activate: run on every new email. The button says Publish & activate.
Connect Gmail and Google Sheets from the checklist, or from the steps, when the routes in the Test tab look right. Until then, leave the accounts empty and keep Send real requests off.
A new message that passes the trigger settings starts a run when Gmail sends the event. Follow runs on the workflow's Executions page (Studio → Usage → Executions). While an automation is paused, events that arrive are skipped. Kovca does not keep them to run later. A failed run is not retried on its own, because the row may already have been appended.
If someone already reads the inbox
You don't need this if a person can read the shared inbox and the volume is small. Gmail can filter on subject:(invoice OR bill), and a spreadsheet is a fine place to type the six fields by hand. A filter does not read the body, and it does not check the date format.
What the workflow adds is the same copy of the six fields on every new message that matches the search you set, a check of those fields, a row only when the status is valid, and a check label otherwise. You still choose the accounts, replace the stand-in search, spreadsheet id, and label ids, and read a sample of results before you activate it. Look up a row runs on the valid path and its result comes back on the output. This template does not skip the row when that result is present, because the catalog does not name the field that means a match.
Make it yours
- Point the search at the real inbox.
to:billing@example.com subject:(invoice OR bill)is a stand-in. Use the search your mailbox actually needs. Set In label once Gmail is connected if the mail already lands under one label. - Replace the label ids.
Label_loggedandLabel_checkare not ids from a mailbox. Use the ids Gmail lists once the account is connected. A display name such as Invoices/Logged is not what Add label sends. - Point both ranges at the real tab.
1kL4mN5oP6qR7sT8uV9wX0yZ1aB2cD3eF4gH5iJ6kL7,Invoices!A:A, andInvoices!A1are stand-ins. The lookup range is the column that should hold the invoice number. The append range locates the table. The first cell of the row is the invoice number, then vendor, invoice date, due date, currency, total, and message id. - Leave invalid, warning, and review records off the sheet. That is already what the false branch does. A missing field, a date that is not
YYYY-MM-DD, and a status other thanvalidget Label check and no row. - Skip a duplicate only after you have seen
result. Look up a row returnsokandresult. The sampleresultis{}. Add a condition on the field a real lookup uses for "no row", and move Append row and Label logged onto that branch. Until you have seen that field, this template still appends when the status isvalid. - Do not expect a PDF attachment to be read. The trigger's event has
body_textand no attachment fields. An invoice that exists only as a PDF is not in the event. - Match the invoice to a purchase order in a different workflow. This one logs header fields from the email body. Check vendor invoices against the purchase order before payment is the one that matches lines to a purchase order. It needs the invoice as structured data, including at least one line.
- Change it without surprising a live mailbox. Edit the draft and publish the changes to the automation. The running version stays pinned until you do.
What it costs
Credits, and only for steps that succeed. Billing is the list.
A Studio test skips the run fee. It does not skip Extract data or Check fields. Extract data is Generative AI, billed by tokens, at least 1 credit, including a test with Send real requests off. Check fields is 5 credits when it succeeds, including that test. The Test panel on the recording showed 6 credits for that run: the Decision AI step and Extract data, with 916 Generative AI tokens. A simulated action is not charged, and an action that fails is not charged. A skipped action is not charged. With Send real requests off, the action that runs returns its sample and adds nothing.
- A Gmail event: 6 credits for the run.
- A published API call: 1 credit for the run.
- Extract data: Generative AI, by tokens, at least 1 credit, on every run.
- Check fields: 5 credits when it succeeds.
- Look up: 2 credits when it runs for real and succeeds. Only the true branch is charged.
- Append row: 2 credits when it runs for real and succeeds. Only the true branch is charged.
- Label logged: 2 credits when it runs for real and succeeds. Only the true branch is charged.
- Label check: 2 credits when it runs for real and succeeds. Only the false branch is charged.
The condition, the text step, and the convert use no credits. A branch that doesn't run isn't charged. The Activate panel adds every step together, including the branch that does not run on the same event, so its number is an upper bound for a live event, and it adds Generative AI by tokens on top. With this template that upper bound is 19 credits per event, plus Extract data: the 6 credit event fee, Check fields, Look up, Append row, and both labels. A live event that looks up, appends, and labels logged is 17 plus Extract data when those three actions succeed (the event fee, Check fields, Look up, Append row, and Label logged). A live event that only applies the check label is 13 plus Extract data. A published API call is 12 plus Extract data when it appends, and 8 plus Extract data when it only applies the check label. The response's credits field is the run's total. See the workflows API, HTTP actions, and automations.