Magic Links API
The magic links resource lets external tools create and maintain subscriber action links. This guide explains where to use magic links, how to match each action with the correct destination, and how to test links before live campaigns.
Manage Subscriber Action Links
Magic links turn a subscriber click into a controlled Mailrith action. A magic link can apply a tag, move a subscriber into a flow, or send the subscriber to a specific destination after Mailrith runs the action.
Use the magic links API when an external campaign builder, migration tool, or integration needs to create and manage subscriber action links without creating those links manually in the app.
Place magic links inside Mailrith emails so Mailrith can identify the subscriber who clicked. Do not use magic links as general public links for anonymous website visitors.
- Before you create the magic link, create the tag, sequence, or destination resource that the link will use.
- Create one magic link for one specific subscriber action.
- If the external campaign builder needs to insert the link later, store the returned magic link ID and public URL in that system.
- Place the public URL inside a Mailrith email. Do not place the public URL on an anonymous public page.
- Send a test email to a test subscriber, then click the link from that email.
- Confirm that the subscriber action appears in Subscribers activity history and that the click appears in Magic Links reporting.
- Create one magic link for one specific subscriber action.
- Name each link so users can tell what will happen when a subscriber clicks.
- Make sure destination URLs and subscriber actions match the campaign copy.
- Test a link from a real test email before you use the link in a live campaign.
Endpoint Overview
GET /v1/magic-links lists magic link records. Item endpoints let integrations inspect, update, or delete one magic link.
POST /v1/magic-links creates a link definition. After you create a magic link, place its public URL inside a Mailrith email. Mailrith runs the action when the subscriber clicks that URL from a tracked email context.
Use the API reference to see the exact action and destination fields. If a link applies a tag or starts a sequence, confirm that the target tag or sequence exists in the same workspace before you create or use the link.
/v1/magic-links List magic links
Returns magic links in the authenticated workspace.
View Schema /v1/magic-links Create a magic link
Creates a magic link in the authenticated workspace.
View Schema /v1/magic-links/{magic_link_id} Get a magic link
Returns one magic link from the authenticated workspace.
View Schema /v1/magic-links/{magic_link_id} Update a magic link
Updates an existing magic link.
View Schema /v1/magic-links/{magic_link_id} Delete a magic link
Deletes a magic link from the authenticated workspace.
View SchemaMagic Link Safety
Because a click can change subscriber state, make magic links easy to understand and audit. A confusing link name or a destination that does not match the action makes campaign review harder.
When you migrate links from another system, confirm both parts of the behavior: the action Mailrith performs on the subscriber and the destination where the subscriber lands after the click.
- Use test subscribers before you send a campaign with a new magic link.
- Do not reuse one magic link for unrelated actions.
- Keep old links available while subscribers may still click old emails, unless you intentionally want the action to stop working.
- Document links created by external systems so users know which system created each link.
Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.