Delivery links
Email each customer a personal opinion link when an order completes, remind those who have not answered, and see who responded.
When you know who bought from you, send them a delivery link. The customer gets a personal email inviting them to share their experience, and the opinion they write is marked as verified, so readers know the writer really was your customer. Call it from wherever your orders complete, such as a checkout webhook or a nightly job.
Links need the link permission, which new API keys include. Each link works for 7 days.
Send the invitation
link.create
import { link } from '@orvelt/business';
export async function inviteAfterOrder(order: { id: string; email: string; firstName: string }) {
const result = await link.create({
projectId: 'PROJECT_ID',
customerEmail: order.email,
customerFirstName: order.firstName,
customerReference: order.id,
});
if (result.error) throw new Error(result.error.message);
// Orvelt has emailed the customer. Do not log the link or token.
return { emailedAt: result.data.emailedAt };
}Field names below use the HTTP API's camelCase. Python uses snake_case, such as customer_email, customer_reference, and send_email.
customerEmailandcustomerFirstName(up to 100 characters) are required. The email greets the customer by first name.customerLastNameis optional, up to 100 characters.customerReferenceis required and can be up to 255 characters. Use your order reference to match the link later.
The response includes the full link, its token and verificationId, expiresAt (ttlSeconds is always 604800 and validityMinutes always 10080), and emailedAt. Anyone who has a link can use it, so keep links out of logs and analytics URLs.
Send it in your own email instead
Pass sendEmail: false to get the link without Orvelt emailing it, then put it in your order confirmation email or an SMS. emailedAt is then null.
One email per customer every 48 hours
A project can email the same customer once every 48 hours. An earlier request returns 429 LINK_EMAIL_COOLDOWN with data.nextEligibleAt before anything is created or counted against your plan, so wait until then instead of retrying. Links created with sendEmail: false skip this limit and do not start it.
If the email itself fails, the link is still created: the response has emailedAt: null and an emailError explaining what to do. Resend that link, using its token as the id, instead of creating another. A concurrent email can also start the cooldown just after creation; you then get the created link with an emailError rather than losing it.
Remind customers who have not answered
link.resend
Find links that are still issued or clicked with link.list, then email the same link again:
import { link } from '@orvelt/business';
const result = await link.resend({ projectId: 'PROJECT_ID', id: 'LINK_ID' });
if (result.error) throw new Error(result.error.message);
console.log(result.data.emailedAt, result.data.nextEmailAt);The 48-hour limit still applies. Expired and submitted links cannot be resent; stop reminding customers once a link reaches either status.
See who responded
link.list
import { link } from '@orvelt/business';
const result = await link.list({
projectId: 'PROJECT_ID',
status: 'submitted',
sort: 'newest',
limit: 25,
});
if (result.error) throw new Error(result.error.message);
console.log(`${result.data.used} of ${result.data.limit} links used this period`);| Status | Meaning |
|---|---|
issued | Created, not opened yet. |
clicked | The customer opened the link and started an opinion. |
submitted | The customer posted the opinion. It carries the delivery_link verification method. |
expired | 7 days passed before the customer posted. |
Filter with status (all by default), query (text search up to 200 characters), and sort (newest or oldest), and page with page and limit. Each link includes its id, verificationId, customer details, link, status, nextEmailAt, and when it was issued, clicked, and submitted. The response also has used and limit for the current plan period, with periodStart and periodEnd.