argorant 0.12.0 → 0.14.0

package/README.md

@@ -46,7 +46,14 @@ CI, and agents.
 | `verify <email>` / `verify --file emails.csv -o out.csv` | Verify your own addresses (verification pool; recent re-checks free) | pool |
 | `find "<first last>" --domain <d>` / `find --file people.csv -o found.csv` | Find a person's work email from a name and company domain, one or a whole list ([details](#find-emails)) | 1 credit found, 0.25 nothing found |
 | `find status \| download \| resume \| cancel <job_id>`, `find pricing` | Manage a find job; show prices, balance and limits | free |
-| `campaigns …` | Live outbound campaigns - **operator keys only**, see below | - |
+| `campaigns …` | Email campaigns, see below | - |
+| `account` | Plan, credits, requests per minute, campaign emails, scopes | free |
+| `lists ls \| create \| show \| people \| rename \| rm \| export` | Saved lists, a page at a time ([details](#lists-exports-credits-and-webhooks)) | free, export 1 credit per valid contact |
+| `exports ls \| status \| download` | Your exports, newest first | free |
+| `companies count \| search \| people` | Companies that match your filters | free |
+| `lookup industries \| countries \| keywords \| technologies \| titles [text]` | The exact labels to use in filters | free |
+| `credits packs \| quote \| buy \| purchases` | Buy a credit pack; asks first, then the saved card or a payment link | the pack price |
+| `webhooks ls \| add \| set \| test \| deliveries \| rm` | Get events sent to your own server | free, Pro plan and up |
 
 ## Phone numbers
 
@@ -205,6 +212,66 @@ needs a paid plan" apart from "something broke".
 command always wins over the stored one, `ARGORANT_API_BASE` overrides both,
 and `argorant logout` removes the file.
 
+## Lists, exports, credits and webhooks
+
+These commands call the API under `/api/v1` and work with any API key that has the right
+permissions. Lists come back a page at a time: `-n` sets the page size, `--cursor` continues
+where the last page ended (the command prints the next cursor), and `--all` reads every page.
+
+```sh
+npx argorant account                                     # plan, credits, requests per minute
+npx argorant lookup industries soft                      # exact labels for --industry
+npx argorant lookup titles "head of"
+npx argorant companies count --country Germany --employees 11-50,51-200
+npx argorant companies search saas --country Germany -n 10
+
+npx argorant lists                                       # your saved lists, newest first
+npx argorant lists create --name "DACH CFOs" --title CFO --country Germany,Austria,Switzerland
+npx argorant lists show 1240
+npx argorant lists people 1240 --all --json              # the people in it, contact details hidden
+npx argorant lists rename 1240 --name "DACH finance leaders"
+npx argorant lists export 1240 -n 500 -o cfos.csv        # 1 credit per valid contact
+npx argorant lists export 1240 --include-phones          # plus 10 credits per phone number returned
+npx argorant lists rm 1240 --yes
+
+npx argorant exports                                     # your exports, newest first
+npx argorant exports status 5521
+npx argorant exports download 5521 -o leads.csv
+
+npx argorant credits packs                               # 500, 5,000, 25,000 and 100,000 credits
+npx argorant credits quote 5000                          # the price, nothing is bought
+npx argorant credits buy 5000                            # asks first, then pays (see below)
+npx argorant credits purchases
+
+npx argorant webhooks add https://example.com/hooks/argorant --events reply.received,reply.positive
+npx argorant webhooks                                    # your webhooks and every event you can pick
+npx argorant webhooks test 3
+npx argorant webhooks deliveries 3
+npx argorant webhooks set 3 --inactive
+npx argorant webhooks rm 3 --yes
+```
+
+`credits buy` shows the quote first and only buys after a yes: at a terminal it asks, anywhere
+else it needs `--yes`. When your workspace saved its card for API and agent purchases and the
+purchase fits the limits you set in Settings, that card is charged right away. Otherwise you get a
+payment link to pay yourself, and the credits are added once the payment goes through.
+`--pay-with link` always gives the link. Bought credits stay valid for 365 days.
+
+`lists rm` and `webhooks rm` work the same way: they ask at a terminal and need `--yes` anywhere
+else. A webhook's signing secret is shown once, when you add it.
+
+### Safe retries and support
+
+Every change the CLI makes through `/api/v1` carries an `Idempotency-Key`. If a command fails
+halfway (a dropped connection, a closed laptop), run it again with your own key to get the
+first answer back instead of doing the work twice:
+
+```sh
+npx argorant credits buy 5000 --yes --idempotency-key buy-5000-oct
+```
+
+Errors show the server's message and a request id. Quote the request id if you contact support.
+
 ## Campaigns and inboxes
 
 Email outreach from the terminal, with any Argorant API key. Nothing sends until you launch.
@@ -215,6 +282,10 @@ argorant campaigns create --name "Q4 CFO outreach" [--daily-limit 40] [--timezon
 argorant campaigns emails set <campaign> --step 1 --subject "Quick question, {{first_name}}" --body-file ./step1.txt
 argorant campaigns emails set <campaign> --step 2 --body "Bumping this." --delay-days 3
 argorant campaigns emails set <campaign> --file emails.json        # whole sequence at once
+argorant campaigns subsequences list <campaign>                   # reply-keyword follow-ups
+argorant campaigns subsequences set <campaign> --file subsequences.json   # up to 5, replaces the set
+#   keywords also match in capitals, as a plural, with a small typo or inside a short sentence;
+#   "not interested" and replies that ask to stop never start a subsequence
 argorant campaigns leads add <campaign> --list <list-id>           # a saved list
 argorant campaigns leads add <campaign> --csv leads.csv            # email, first_name, last_name, company, title
 argorant campaigns senders set <campaign> --emails a@x.com,b@y.com # or --all
@@ -235,6 +306,40 @@ argorant inboxes connect-google --admin admin@yourdomain.com       # lists mailb
 argorant inboxes connect-google --admin admin@yourdomain.com --emails a@x.com,b@x.com   # or --all
 ```
 
+### Mailboxes from any email provider (SMTP and IMAP)
+
+Zoho, Fastmail, Yahoo, iCloud, IONOS, your web host or any other provider connect with their server settings.
+Argorant signs in twice before it saves anything: once to send (SMTP) and once to read replies (IMAP). A mailbox
+connects only when both work. The password is stored safely and never shown again; many providers need an app
+password instead of the normal one. Google and Microsoft mailboxes connect with their own sign-in instead.
+
+```
+argorant inboxes presets                                           # provider keys for --preset
+argorant inboxes test-smtp --email anna@acme.com --preset zoho     # checks sending and reading replies, saves nothing
+argorant inboxes connect-smtp --email anna@acme.com --preset zoho --name "Anna Weber"
+argorant inboxes connect-smtp --email anna@acme.com --smtp-host mail.acme.com --smtp-port 587 --imap-host mail.acme.com
+argorant inboxes connect-smtp --csv mailboxes.csv                  # many at once, a result per row
+```
+
+The password is never taken on the command line. Put it in an environment variable and name it with
+`--password-env NAME`, set `ARGORANT_MAILBOX_PASSWORD`, or type it when asked. `--imap-password-env NAME` sets a
+different password for reading replies. Connecting the same address again replaces its settings, which is how a
+mailbox is reconnected after a password change.
+
+CSV columns: `email, sender_name, preset, smtp_host, smtp_port, smtp_security, smtp_username, smtp_password,
+imap_host, imap_port, imap_security, imap_username, imap_password, daily_limit`. Each row needs `email`,
+`smtp_password` (or `password`) and either `preset` or `smtp_host` + `smtp_port` + `imap_host`. Empty columns take
+the defaults: the username is the email address, reading replies uses the sending sign-in, port 993, 25 emails a
+day. Security is `ssl`, `starttls` or `none`. Use port 587 for sending; if you give 465, Argorant tries 587 and
+saves 587 when it works. Rows go up 25 at a time; the command exits 1 when any row did not
+connect.
+
+```
+email,sender_name,preset,smtp_password
+anna@acme.com,Anna Weber,zoho,app-password-1
+ben@acme.com,Ben Hill,zoho,app-password-2
+```
+
 New mailboxes on their own new domains, ordered from the terminal. The quote shows every domain with its
 first-year and renewal price, the mailboxes, the total and how it is paid. When your workspace saved its card
 for API and agent purchases (you ticked that box when you paid an earlier order, and the setting in