# Delivery links

URL: /docs/developers/collect/delivery-links

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.

```mermaid
flowchart LR
  accTitle: Delivery link statuses
  accDescr: A new link is issued. When the customer opens it and starts an opinion it becomes clicked, and when they submit it becomes submitted. A link not submitted within 7 days becomes expired.
  issued["issued"] -->|Opened| clicked["clicked"]
  clicked -->|Posted| submitted["submitted"]:::result
  issued -.->|7 days| expired["expired"]
```

Links need the `link` permission, which new API keys include. Each link works for 7 days.

## Send the invitation [#send-the-invitation]

### `link.create` [#linkcreate]

**TypeScript SDK**

```ts
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 };
}
```

**Python SDK**

```python
import os
from orvelt_business import Orvelt

def invite_after_order(order):
    with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
        result = client.link.create(
            project_id="PROJECT_ID",
            customer_email=order["email"],
            customer_first_name=order["firstName"],
            customer_reference=order["id"],
        )
        # Orvelt has emailed the customer. Do not log the link or token.
        return {"emailedAt": result.emailed_at}
```

Field names below use the HTTP API's camelCase. Python uses snake_case, such as `customer_email`, `customer_reference`, and `send_email`.

- `customerEmail` and `customerFirstName` (up to 100 characters) are required. The email greets the customer by first name.
- `customerLastName` is optional, up to 100 characters.
- `customerReference` is 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 [#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 [#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 [#remind-customers-who-have-not-answered]

### `link.resend` [#linkresend]

Find links that are still `issued` or `clicked` with `link.list`, then email the same link again:

**TypeScript SDK**

```ts
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);
```

**Python SDK**

```python
import os
from orvelt_business import Orvelt

with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    result = client.link.resend(project_id="PROJECT_ID", id="LINK_ID")
    print(result.emailed_at, result.next_email_at)
```

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 [#see-who-responded]

### `link.list` [#linklist]

**TypeScript SDK**

```ts
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`);
```

**Python SDK**

```python
import os
from orvelt_business import Orvelt

with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    page = client.link.list(
        project_id="PROJECT_ID",
        status="submitted",
        sort="newest",
        limit=25,
    )
    print(f"{page.result.used} of {page.result.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`](/docs/developers/pagination). 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`.