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 align actions with destinations, and how to test links before live campaigns.
6 min read
Manage Subscriber Action Links
Magic links turn a subscriber click into a controlled Mailrith action. A link can represent an action such as applying a tag, moving a subscriber into a flow, or sending the subscriber to a specific destination after the action runs.
Use the magic links API when an external campaign builder, migration tool, or integration needs to create and maintain subscriber action links without manually building them in the app.
Magic links are meant to be placed inside Mailrith emails where Mailrith can understand the subscriber context. Do not treat them as general public links for anonymous website visitors.
- Create the tag, sequence, or destination resource the link will use before creating the magic link.
- Create one magic link for one clear subscriber action.
- Store the returned magic link ID and public URL in the external campaign builder if it needs to insert the link later.
- Place the public URL inside a Mailrith email, not on an anonymous public page.
- Send a test email and click the link with a test subscriber.
- Confirm the subscriber action in Subscribers activity history and Magic Links reporting.
- Create one magic link for one clear subscriber action.
- Name links in a way that tells users what will happen when someone clicks.
- Keep destination URLs and subscriber actions aligned with the campaign copy.
- Test a link from a real test email before using it 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 creating a magic link, place its public URL inside a Mailrith email. The action runs when the subscriber clicks that URL from a tracked email context.
Use the API reference for exact action and destination fields. If a link applies a tag or starts a sequence, make sure that target resource exists in the same workspace.
/v1/magic-links List magic links
Returns magic links available 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 a magic link in the authenticated workspace.
View Schema /v1/magic-links/{magic_link_id} Update a magic link
Updates an existing magic link in place.
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, keep magic links easy to understand and easy to audit. A confusing link name or mismatched destination makes campaign review harder.
When migrating links from another system, confirm both parts of the behavior: what Mailrith does to the subscriber and where the subscriber lands after the click.
- Use test subscribers before sending a campaign with a new magic link.
- Avoid reusing one magic link for unrelated actions.
- Keep old links available while old emails may still be clicked, unless the action must intentionally stop working.
- Document links created by external systems so users know where they came from.
Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.
Related Guides
Manage automation definitions with triggers, branches, actions, conditions, and review safeguards.
Use tags as clear subscriber labels for targeting, forms, imports, and automation conditions.
Browse generated endpoint details and download the exact OpenAPI contract for tooling.