If you searched for "mailto html", "html mailto link", or "mailto parameters", you likely need one reliable answer: how to build a mailto link that behaves correctly across browsers and email clients.

This guide covers exact syntax, URL encoding rules, common mistakes, and when to use a backend email workflow instead.

A mailto link is an anchor tag with an that starts with . When users click it, their default email client opens with pre-filled fields.

Mailto is useful for lightweight contact actions, but it is not a full email-delivery system.

Mailto syntax basics

General pattern:

Rules:

  • use before the first parameter
  • use between additional parameters
  • URL-encode values ( for spaces)
  • keep parameters lowercase for consistency

Common mailto parameters

ParameterPurposeExample
pre-fills email subject
pre-fills body text
visible copy recipient
hidden copy recipient

Example with multiple fields:

How to encode mailto values correctly

Most mailto bugs come from bad encoding.

Use:

  • for spaces
  • for new lines
  • for literal
  • for literal

Example with line breaks:

Multiple recipients with mailto

You can add multiple recipients separated by commas:

Keep recipient lists short. Long links can break in some clients.

Can mailto include attachments?

Not reliably.

There is no consistent cross-client standard for attaching local files via mailto links. If attachments are required, use:

  • a file upload form
  • API-based sending workflows

Related: Email attachments API and attachments guide.

Common failure points:

  • no default email client configured
  • mobile app/browser mismatch
  • malformed query string
  • unencoded special characters
  • user environment restrictions

Mailto opens a client; it does not confirm delivery.

Troubleshooting checklist

  1. Confirm link starts with
  2. Validate recipient format
  3. Validate and placement
  4. URL-encode subject/body text
  5. Test in desktop + mobile browsers
  6. Test with Gmail/Outlook/Apple Mail defaults

Security and spam considerations

Publishing plain emails in HTML can increase scraping risk.

Mitigations:

  • use role inboxes (, ) instead of personal addresses
  • rotate exposed addresses used for public pages
  • add form-based fallback for high-value flows

For programmable receive-side workflows, see email API.

When to use mailto vs API sending

Use when:

  • you need very low implementation overhead
  • user can choose/send via local client
  • delivery tracking is not required

Use API/backend sending when:

  • you need reliable transactional delivery
  • attachments/templates are required
  • you need analytics, retries, and auditing

Related implementation guides:

Mailto reliability checklist

Use this checklist to avoid conversion and support drop-offs:

  1. Test mailto flows in an email sandbox across desktop and mobile defaults.
  2. Add form/API fallback paths with email integration testing coverage.
  3. Capture contact-flow events through email webhooks when users choose API-backed forms.
  4. Route follow-up and escalation logic via email automation routing.
  5. Validate end-to-end outcomes with deliverability tests.

This keeps simple mailto UX while protecting critical inbound communication paths.

FAQ

Not consistently. Behavior depends on browser, OS, and configured default client.

Yes. Add both as query parameters and encode values.

Is mailto good for contact forms?

It is acceptable for simple contact flows, but backend forms are more reliable and controllable.

The system default email handler controls which app opens.

Final take

Mailto links are useful for lightweight contact UX, but they are fragile for mission-critical communication.

If email delivery is part of signup, billing, support, or product automation, implement backend/API workflows and test full send-receive behavior.