How to Send Urlwatch Change Alerts to Email

To email urlwatch change alerts, enable its email reporter in the global urlwatch.yaml, set the sender and recipient, choose SMTP or local sendmail, test with urlwatch --test-reporter email, then schedule urlwatch to run at the cadence you want. Email is sent when a run produces reportable results; the scheduler determines how often urlwatch checks.

1. Open the global configuration

Run the built-in editor to open urlwatch’s global configuration:

urlwatch --edit-config

Reporter settings belong under the top-level report key. The exact file location depends on your installation and user account, so using the command avoids guessing which configuration file urlwatch is reading.

2. Enable the email reporter

Use this as a starting point. Replace the example addresses and transport values with settings for your own mail system.

report:
  email:
    enabled: true
    from: "urlwatch@example.com"
    to: "you@example.com"
    method: smtp
    smtp:
      host: "smtp.example.com"
      port: 587
      auth: true
      starttls: true
    subject: "{count} changes: {jobs}"

The required choices are enabling the reporter, supplying a sender and recipient, and selecting a delivery method. SMTP sub-options vary by provider; consult your provider’s current connection requirements. The example illustrates the shape of the configuration, not universal host or port values.

Optional report formatting

The email configuration supports a subject template. The example {count} changes: {jobs} includes the number of changes and affected jobs. You can also set html: true if you want the email reporter to inherit HTML formatting.

3. Choose a delivery method

Method	Use it when	What to check
`smtp`	An SMTP server is available from the machine running urlwatch.	Provider host, port, authentication, TLS mode, sender authorization, and credentials.
`sendmail`	A local mail transfer agent is installed and already configured.	The local mail service works and urlwatch can invoke its executable. The configuration can specify a sendmail executable path when needed.

Urlwatch’s email guidance also names managed delivery services such as Amazon SES and Mailgun. These are possible ways to obtain email delivery; urlwatch does not require a paid provider. Check the selected provider’s current account requirements and SMTP settings.

Store SMTP credentials safely

Where keyring support is available, use urlwatch’s credential command to prompt for and store the SMTP password:

urlwatch --smtp-login

The command checks the login and stores the credential in the keyring for later runs. The documentation also describes insecure_password for environments where a keyring cannot be used, but this stores a password in plaintext. Prefer the keyring; if you must use plaintext, understand that anyone who can read the configuration may be able to read the credential, and avoid using a primary email account for that setup.

4. Test delivery before scheduling

Ask urlwatch to test the configured reporter:

urlwatch --test-reporter email

If the test reports an error, rerun with verbose logging for more detail:

urlwatch --test-reporter email --verbose

Confirm the email reporter is enabled and that the selected method, sender, recipient, and transport credentials match your mail setup. A reporter test checks the notification path; it does not establish that every scheduled job will produce a message.

5. Schedule urlwatch

Urlwatch checks jobs when it runs. Schedule the command with cron or another scheduler to define the interval. The urlwatch introduction recommends not running it more frequently than every 30 minutes.

For example, a cron entry that runs every 30 minutes could look like this:

*/30 * * * * /path/to/urlwatch

Replace /path/to/urlwatch with the executable path for your installation. Run urlwatch manually as the same operating-system user first, so the scheduled process uses the expected configuration and credential keyring.

When does urlwatch send an email?

Urlwatch retrieves each job’s output, applies configured filters, compares it with the previous retrieval, and invokes enabled reporters when there are reportable results. The default reporting configuration includes changes, new pages, and errors, while unchanged pages are not included. Reporter display settings can alter whether new jobs, errors, unchanged items, and empty diffs appear.

As the urlwatch documentation puts it, “The checking interval is defined by how often you run urlwatch.” A frequent scheduler does not guarantee an email each time: if there are no reportable results, the report may have nothing to send.

Common problems and fixes

Symptom	Likely cause	What to do
No email arrives	The reporter is disabled, the test was not run, or the transport is misconfigured.	Run `urlwatch --test-reporter email`; verify `report.email.enabled`, method, sender, recipient, and transport settings.
SMTP authentication fails	Wrong credentials, unsupported authentication setup, or a provider-specific account requirement.	Check the provider’s current SMTP instructions and credential; use `urlwatch --smtp-login` to store and check the login.
SMTP connection or TLS error	Host, port, or TLS mode does not match the provider.	Use the provider’s current values for host, port, and TLS/authentication options rather than copying an example blindly.
Sendmail cannot be found or invoked	No local mail transfer agent is installed, or the executable path is wrong.	Install and configure a local mail transfer agent or use SMTP; set the sendmail executable path if required.
Only some runs produce email	A run had no reportable changes, or unchanged results are excluded.	Review the jobs’ results and reporter display settings for changes, new pages, errors, unchanged items, and empty diffs.
Checks run too often or too rarely	The scheduler interval does not match the desired cadence.	Adjust cron or the other scheduler. Urlwatch’s documented recommendation is no more often than every 30 minutes.
Manual runs work, scheduled runs fail	The scheduler may use a different account, environment, configuration, executable path, or keyring access.	Run the scheduled command as the intended user and verify it can access the same configuration and stored credentials.

For detailed diagnostics, use --verbose when testing the reporter. Avoid putting SMTP passwords in command history or shared configuration files.

Or skip the browser setup

If the task is to capture a page as an image or PDF rather than monitor it for changes, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns an image or PDF; see the API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Urlwatch is for change monitoring; ScreenshotNeo is for capturing a page now.

FAQ

Can urlwatch email every check, including unchanged pages?

Reporter display settings control whether unchanged results and empty diffs appear. The default configuration excludes unchanged pages.

Does urlwatch need Gmail or another specific provider?

No. Use an SMTP server you can access, or choose local sendmail if a configured mail transfer agent is available.

Does changing the email configuration change how often pages are checked?

No. The scheduler’s run frequency sets the checking interval; email settings control report delivery.