Public routes: Email links
The links in PurrCRM’s own emails: clicks, opens, unsubscribing and the preference centre. PurrCRM writes these; you do not call them.
| What it does | Route |
|---|---|
| Follow a link in an email | GET /public/v1/email/c/{token} |
| Count a click the app opened | POST /public/v1/email/c/{token} |
| Read an email’s unsubscribe page | GET /public/v1/email/lists/{token} |
| An email’s open pixel | GET /public/v1/email/o/{token} |
| Open the unsubscribe link | GET /public/v1/email/unsubscribe/{token} |
| Unsubscribe in one click | POST /public/v1/email/unsubscribe/{token} |
| Read the preference centre | GET /public/v1/preferences/{token} |
| Save the preference centre | POST /public/v1/preferences/{token} |
Follow a link in an email
Section titled “Follow a link in an email”GET /public/v1/email/c/{token}
Counts the click and redirects to the link the email’s own version holds.
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
token (required) | path | The signed token from the email’s link. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 302 | none | A redirect |
Count a click the app opened
Section titled “Count a click the app opened”POST /public/v1/email/c/{token}
The same click, when the app opened the email’s link itself.
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
token (required) | path | The signed token from the email’s link. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 204 | none | Done, with nothing to say |
Read an email’s unsubscribe page
Section titled “Read an email’s unsubscribe page”GET /public/v1/email/lists/{token}
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
token (required) | path | The signed token from the email’s link. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | object | OK |
| 404 | problem | Not found, or the part is switched off. |
| 429 | problem | Too many requests: wait for Retry-After. |
An email’s open pixel
Section titled “An email’s open pixel”GET /public/v1/email/o/{token}
Always a 1×1 GIF; the first fetch counts the open.
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
token (required) | path | The signed token from the email’s link. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | image/gif | OK |
Open the unsubscribe link
Section titled “Open the unsubscribe link”GET /public/v1/email/unsubscribe/{token}
Redirects to the unsubscribe page, which asks first.
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
token (required) | path | The signed token from the email’s link. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 302 | none | A redirect |
Unsubscribe in one click
Section titled “Unsubscribe in one click”POST /public/v1/email/unsubscribe/{token}
The one-click unsubscribe (RFC 8058) a mail app posts, and the unsubscribe page’s confirm: the person leaves that email’s topic by email.
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
token (required) | path | The signed token from the email’s link. |
source | query |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | object | OK |
| 303 | none | A redirect |
| 404 | problem | Not found, or the part is switched off. |
| 429 | problem | Too many requests: wait for Retry-After. |
Read the preference centre
Section titled “Read the preference centre”GET /public/v1/preferences/{token}
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
token (required) | path | The signed token from the email’s link. |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | PublicPreferences | OK |
| 404 | problem | Not found, or the part is switched off. |
| 429 | problem | Too many requests: wait for Retry-After. |
Save the preference centre
Section titled “Save the preference centre”POST /public/v1/preferences/{token}
Takes JSON, or the page’s plain form (which is then redirected back to the page).
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
token (required) | path | The signed token from the email’s link. |
Body (application/json): PreferencesBody
| Field | Type | Description |
|---|---|---|
all_off | boolean | |
choices | array of PreferenceChoice | |
wording | string |
Answers
| Status | Body | Meaning |
|---|---|---|
| 200 | PublicPreferences | OK |
| 303 | none | A redirect |
| 404 | problem | Not found, or the part is switched off. |
| 429 | problem | Too many requests: wait for Retry-After. |