Prefill a Desktop Email with xdg-email

xdg-email opens your desktop email composer with the recipients, subject, body and attachment already filled in, but never sends it. The composer opens and you decide whether to edit and send the draft.

This guide describes xdg-utils 1.1.3, installed here as package version 1.1.3-4.1ubuntu3. Allow about ten minutes. You need a graphical desktop session, xdg-utils, a configured preferred email application and read access to any file you attach. These examples are ordinary user commands. Do not use xdg-email as root.

1. Check the installed command

Confirm which command is on your path and record the version. This does not open an email application:

$ command -v xdg-email
/usr/bin/xdg-email
$ xdg-email --version
xdg-email 1.1.3

The command is a desktop integration tool. It relies on the preferred mail composer associated with your session, so it is not a replacement for an SMTP client and will not work as a dependable batch-mail mechanism from a server shell, cron job or container.

Checkpoint: if command -v finds nothing, install or enable the distribution's xdg-utils package before continuing. If the command exists but no composer opens later, investigate the desktop association and session before changing the command.

2. Open a simple addressed draft

Start with one recipient. Quote the address so that shell characters, if later introduced by a generated value, do not become shell syntax:

$ xdg-email '[email protected]'

Your preferred composer should open with the To field prefilled. The command normally returns after handing the request to the desktop application. There may be no useful terminal output.

Checkpoint: confirm the recipient in the composer before sending. A zero exit status means the action succeeded according to xdg-email; it does not prove that the message was sent. The user still controls editing and sending in the mail application.

3. Prefill the subject and body

Use --subject and --body when you want a repeatable draft template. Keep each value quoted:

$ xdg-email \
    --subject 'Project review' \
    --body 'Hello,

Here is the draft for your review.

Regards,
Alex' \
    '[email protected]'

The body option accepts line breaks. Treat it as initial content, not as a way to bypass the composer. The recipient can change or remove the text before sending.

If the body contains shell variables, decide deliberately whether they should expand. Use single quotes for literal text, as above. Use double quotes only when expansion is intended, and inspect the resulting draft before sending. This matters especially for passwords, tokens and private data: do not put secrets in command history or a process-visible command line.

4. Add copied and blind-copied recipients

Add one address with --cc or --bcc. These options add fields to the draft; they do not send anything:

$ xdg-email \
    --cc '[email protected]' \
    --bcc '[email protected]' \
    --subject 'Access review' \
    --body 'Please review the attached report.' \
    '[email protected]'

Check the Bcc field carefully in the composer. Blind copies are hidden from other recipients, but they are still real recipients and can disclose the message to someone you did not intend to include. Do not put an address containing whitespace into an unquoted shell word.

Multiple direct recipients can be separate arguments:

$ xdg-email '[email protected]' '[email protected]'

Use the address syntax accepted by the configured composer. For a display name, the installed manual gives this form:

$ xdg-email 'Project Desk <[email protected]>'

5. Attach an existing file

Pass an existing readable path with --attach:

$ report='/tmp/report.pdf'
$ test -r "$report" && xdg-email \
    --attach "$report" \
    --subject 'Monthly report' \
    --body 'The report is attached.' \
    '[email protected]'

The test is a local read check. It prevents you from opening a draft when the expected file is absent or unreadable. xdg-email reports missing files with exit code 2 and unreadable attachment files with exit code 5.

Some email applications continue reading the attachment after xdg-email returns. Keep the file at the same path until the composer has imported it and the draft is ready. Do not delete or move it immediately after the command.

There is no xdg-email undo operation for an attachment. Closing the unsent draft without saving removes the draft only if your mail application offers that behaviour. If you save it, use the application's normal draft deletion controls. The command itself does not delete the original file.

6. Use a mailto URI for a compact draft

A mailto: URI can carry a recipient and supported fields:

$ xdg-email 'mailto:[email protected]?subject=Build%20finished&body=The%20build%20passed%20checks.'

Spaces and other URI characters must be percent-encoded. xdg-email supports the to, cc, subject and body fields in a mailto URI. Other fields are silently ignored by this command. The URI form does not replace shell quoting: quote the whole URI so the shell does not interpret its punctuation.

Prefer the long options when a script is assembling values. They make attachment handling and shell quoting easier to review. Do not concatenate untrusted input into a mailto URI without proper URI encoding, and do not paste confidential values into a URI that may appear in shell history or logs.

7. Diagnose failures without guessing

Capture the status immediately after a failed invocation:

$ xdg-email --attach /tmp/file-that-does-not-exist '[email protected]'
$ status=$?
$ printf 'xdg-email status: %s\n' "$status"
xdg-email status: 2

The documented status meanings are:

• 1: command-line syntax error;
• 2: a file passed on the command line does not exist;
• 3: a required tool could not be found;
• 4: the desktop action failed;
• 5: xdg-email lacks permission to read a passed file.

For extra diagnostics, set XDG_UTILS_DEBUG_LEVEL to a non-zero number for one invocation:

$ XDG_UTILS_DEBUG_LEVEL=2 xdg-email '[email protected]'

A higher value requests more verbose reporting on standard error. Treat debug output as potentially sensitive because it may expose addresses or paths. If the command returns 0 but no composer appears, check that you are in the intended graphical session and that a preferred mail application is configured. Elevated privileges are not a general fix: root may have a different desktop environment, different associations and different access to the user's session.