Public routes: Email hooks
Where your mail provider posts replies, bounces and complaints, signed with the app’s inbound secret.
| What it does | Route |
|---|---|
| Bounces and complaints, for one app | POST /public/v1/apps/{key}/email-events |
| A reply by email, for one app | POST /public/v1/apps/{key}/inbound-email |
| Bounces and complaints | POST /public/v1/email-events |
| A reply by email | POST /public/v1/inbound-email |
Bounces and complaints, for one app
Section titled “Bounces and complaints, for one app”POST /public/v1/apps/{key}/email-events
Your mail provider’s bounces, complaints and deliveries, signed the same way. A hard bounce or a complaint puts the address on the app’s suppression list.
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
key (required) | path | The app’s public key (app_…). |
X-CRM-Signature | header | t=<unix seconds>,v1=<hex HMAC-SHA256 of “<t>.<body>”> under the inbound secret; refused more than five minutes from now. |
Body (application/json): EmailEvent
| Field | Type | Description |
|---|---|---|
address (always) | string | |
detail | string | |
hard | boolean | A bounce that is permanent; a soft one is counted and suppresses nothing. |
id (always) | string | The provider’s id for the event: the same event posted twice is counted once. |
kind (always) | EmailEventKind (one of bounce, complaint, delivered) | |
message_id (always) | string | |
occurred_at (always) | string (date-time) |
Answers
| Status | Body | Meaning |
|---|---|---|
| 202 | none | Accepted |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 413 | problem | Too large. |
| 503 | problem | Not set up here yet. |
A reply by email, for one app
Section titled “A reply by email, for one app”POST /public/v1/apps/{key}/inbound-email
Your mail provider’s inbound hook, through whatever turns its post into this shape and signs it with the app’s inbound secret (X-CRM-Signature). The reply is threaded into the user’s conversation.
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
key (required) | path | The app’s public key (app_…). |
X-CRM-Signature | header | t=<unix seconds>,v1=<hex HMAC-SHA256 of “<t>.<body>”> under the inbound secret; refused more than five minutes from now. |
Body (application/json): InboundEmail
| Field | Type | Description |
|---|---|---|
from (always) | string | |
id (always) | string | The provider’s id for the message: the same message posted twice is threaded once. |
received_at (always) | string (date-time) | |
subject | string | |
text (always) | string | The plain-text body, the quoted email under the reply still in it: PurrCRM keeps the reply alone. |
to (always) | array of string |
Answers
| Status | Body | Meaning |
|---|---|---|
| 202 | object | Accepted |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 413 | problem | Too large. |
| 503 | problem | Not set up here yet. |
Bounces and complaints
Section titled “Bounces and complaints”POST /public/v1/email-events
The same events, signed with the deployment’s inbound secret.
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
X-CRM-Signature | header | t=<unix seconds>,v1=<hex HMAC-SHA256 of “<t>.<body>”> under the inbound secret; refused more than five minutes from now. |
Body (application/json): EmailEvent
| Field | Type | Description |
|---|---|---|
address (always) | string | |
detail | string | |
hard | boolean | A bounce that is permanent; a soft one is counted and suppresses nothing. |
id (always) | string | The provider’s id for the event: the same event posted twice is counted once. |
kind (always) | EmailEventKind (one of bounce, complaint, delivered) | |
message_id (always) | string | |
occurred_at (always) | string (date-time) |
Answers
| Status | Body | Meaning |
|---|---|---|
| 202 | none | Accepted |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 413 | problem | Too large. |
| 503 | problem | Not set up here yet. |
A reply by email
Section titled “A reply by email”POST /public/v1/inbound-email
The same hook for a deployment whose reply addresses name the app themselves, signed with the deployment’s inbound secret.
Needs: nothing: no credential.
Parameters
| Name | In | Description |
|---|---|---|
X-CRM-Signature | header | t=<unix seconds>,v1=<hex HMAC-SHA256 of “<t>.<body>”> under the inbound secret; refused more than five minutes from now. |
Body (application/json): InboundEmail
| Field | Type | Description |
|---|---|---|
from (always) | string | |
id (always) | string | The provider’s id for the message: the same message posted twice is threaded once. |
received_at (always) | string (date-time) | |
subject | string | |
text (always) | string | The plain-text body, the quoted email under the reply still in it: PurrCRM keeps the reply alone. |
to (always) | array of string |
Answers
| Status | Body | Meaning |
|---|---|---|
| 202 | object | Accepted |
| 400 | problem | The request could not be read: the problem names the field. |
| 401 | problem | No credential, or one that is not right. |
| 413 | problem | Too large. |
| 503 | problem | Not set up here yet. |