cancel_bulk_job
ChatGPTUse this when the user asks to stop a bulk job that is still pending or running and has confirmed it. Stops the remaining checks and releases the credits reserved for them. Checks already completed stay charged and their results are kept. Works only on the connected account's own jobs and cannot cancel a finished job. Do not use this to delete results or undo completed checks.
download_bulk_results
ChatGPTUse this when the user wants to download or export the results file of a finished bulk job. Returns a download link to the same file the MailValid dashboard gives: every verification column, with the user's original file columns appended at the end. filter limits the rows to one result class. The link works for 15 minutes; share it with the user. Works for completed or cancelled jobs. Reading results uses no credits. Do not use this to build or rewrite the file yourself, or for a job that is still running (use get_bulk_job).
get_bulk_job
ChatGPTUse this when the user asks about the progress or results of a bulk job, using the job_id MailValid returned. Returns the job status and up to 100 results per call; pass next_offset to read the next page. Once the job has finished, the first page also has a summary of every result by status and the top reasons; use it to tell the user how many were good or bad and why, instead of paging through results. Only reads jobs that belong to the connected account. Does not start checks or use credits. Do not use this to list all jobs (use list_bulk_jobs).
get_credit_balance
ChatGPTUse this when the user asks how many MailValid verification credits they have. Returns the connected account's current balance. Read only: it does not buy, sell or change credits.
get_profile
ChatGPTUse this when you need to know which MailValid account is connected, for example when the user asks which account they are using. Returns the account name, email and a stable opaque ID (not the internal user ID). Read only.
list_bulk_jobs
ChatGPTUse this when the user wants to see their recent bulk verification jobs, for example to find a job_id. Lists the connected account's jobs, newest first, with status and progress. search matches a file name or the start of a job ID. Does not use credits. Do not use this to read a job's results (use get_bulk_job).
open_mailvalid
ChatGPTUse this when the user wants to open the MailValid workspace to check an address or a CSV/TXT list themselves, or to browse their jobs and results. Opens the workspace only: it does not start a check, reserve credits or upload a file. When opened from a file, it only previews the file the user selected. The user picks the email column and approves credit use in the workspace before any check runs. Do not use this to run a check directly (use verify_email, submit_bulk_verification or the file tools). Do not use this just because the user attached a CSV/TXT file and asked you to verify it: pass the file to preview_email_file, then its preview_id to verify_email_file. Only open the workspace when the user asks to open it or to work through the file themselves.
open_mailvalid_settings
ChatGPTUse this when the user wants to change how the MailValid workspace is displayed. Opens the workspace display preferences. Does not change the account, billing or API settings.
preview_email_file
ChatGPTUse this when the user attached a CSV or TXT file of email addresses and wants them verified or checked. Reads the whole file and returns the real counts before anything runs: rows, unique addresses, which column holds the emails, the other columns that will be kept, and the most credits the job can use. Starts no check and uses no credits. Tell the user these numbers and ask them to approve, then call verify_email_file with the returned preview_id (not the file). If the wrong column was picked, call this again with email_column (the column name or its 1-based number) and use the new preview_id. For an Excel or Numbers sheet, convert it to CSV yourself first (keep the header row and every column) and pass that CSV; do not ask the user to convert it. Do not use this for addresses typed in the chat (use submit_bulk_verification).
submit_bulk_verification
ChatGPTUse this when the user typed or pasted a list of email addresses into the chat and has approved the credit use. Starts a bulk job on the connected account. Exact duplicates are removed, up to one existing credit is reserved per unique address, and the final charge is settled when the job finishes; unknown results use no credit. Account bulk limits apply. To retry the same submission without a second job or reservation, send the same UUID request_id. Always tell the user the returned message, then use get_bulk_job to read progress and download_bulk_results for the results file. Do not use this for addresses in an attached CSV or TXT file: use preview_email_file and verify_email_file, which read the whole file and keep its other columns. Do not use this for a single address (use verify_email), for addresses the user did not provide, or to send messages.
submit_workspace_list
ChatGPTUse this when the MailValid workspace submits a list the user picked and approved in the workspace. Called by the workspace only (hidden from the assistant): it carries the file's other columns, which are added back to the results download. Do not use this from the chat; use submit_bulk_verification or verify_email_file.
verify_email
ChatGPTUse this when the user asks to check one specific email address they supplied and may process. Runs syntax, DNS, MX and mailbox checks and saves the result to the connected MailValid account. A valid, invalid, catch_all or do_not_mail result uses one existing credit; unknown uses none. To retry the same check without a second charge, send the same UUID request_id; a new request_id or none can be charged again. Do not use this for two or more addresses (use submit_bulk_verification), to find or guess addresses, or to send email. A result does not prove identity, consent or delivery.
verify_email_file
ChatGPTUse this when the user approved verifying the addresses in a CSV or TXT file they attached. Pass the preview_id from preview_email_file; the file itself is not needed again. Starts one bulk job with exactly the addresses the user approved in that preview. The file's other columns are kept and added back to the results download, like the MailValid dashboard upload. Up to one existing credit is reserved per unique address; unknown results use no credit. Always tell the user the returned message, then use get_bulk_job for progress and download_bulk_results for the file. To retry without a second job, send the same UUID request_id. Do not use this for addresses typed in the chat (use submit_bulk_verification).