Delivery methods

Every gift in an order has a delivery object that says how it reaches the recipient. There are three methods: email and phone, where we send the gift for you, and link, where you deliver it yourself. One order can mix all three.

Email

Set method to email and give the address:

"delivery": { "method": "email", "email": "sam@example.com" }

What the recipient gets. We email the gift right away. The sender name reads "The Acme team (via On Me)", using your sender_name or, if you didn't send one, your organization name, and the subject line says who sent the gift. The email links to the gift page, where the recipient opens and claims it.

What you get back. The gift echoes the address, trimmed and lowercased, with status set to sent:

"delivery": { "method": "email", "status": "sent", "email": "sam@example.com" }

sent means we've accepted the gift for delivery. If the email later can't be delivered, the status changes to failed; see Fixing a failed delivery.

SMS

Set method to phone, not sms, and give the number:

"delivery": { "method": "phone", "phone": "+1 (415) 555-1234" }

The number must start with + and a country code. Spaces, dashes, dots and parentheses are fine, and we store the number in E.164 format:

A number that isn't valid for its country is rejected too. Either way you get parameter_invalid with a param such as gifts[0].delivery.phone, and the order isn't created.

What the recipient gets. We text the gift right away. The message greets the recipient by recipient_name if you set one ("Hi Sam", otherwise "Hi there"), names the sender and the category, and includes the link to the gift page. It ends with a line saying who sent it, which includes the email address of your organization's billing contact, or of an admin if no billing contact is set.

What you get back. The gift echoes the number in E.164:

"delivery": { "method": "phone", "status": "sent", "phone": "+14155551234" }

As with email, sent means accepted for delivery, and it changes to failed if the text can't be delivered.

Link

Set method to link. There's nothing else to send:

"delivery": { "method": "link" }

What the recipient gets. Nothing from us. We don't email or text anyone. You deliver the link through your own channel: your app, a chat message, an internal tool, a printed card.

What you get back. The gift includes delivery.link, the URL of the gift page:

"delivery": { "method": "link", "status": "sent", "link": "https://gift.onme.com/Xq7mT2pLk9RwZ4vB" }

The recipient opens the link, sees the gift, and claims it, the same page an email or SMS recipient lands on. For a link gift, sent means the link is ready; a link gift never reaches failed.

Delivery status

Each gift's delivery.status tells you how far it has got:

The status shows the furthest point a gift has reached. A gift that failed, was redirected and then claimed reads claimed.

To track gifts, poll GET /v1/gifts/{gift_id} for a single gift, or page through GET /v1/gifts to check many at once. Webhooks are planned, so you won't need to poll forever.

curl https://api.onme.com/v1/gifts/g-XLotjYqCLoI9pgf0jKYl5gXsNzxkBANTiq1VyivdeRA \
  -H "Authorization: Bearer $ONME_API_KEY"

Link expiry

A gift link stops working a year after it was issued. You don't need to track that date. Fetch the gift with GET /v1/gifts/{gift_id} whenever you're about to share or re-share its link: if the link has expired and the gift hasn't been claimed, that response carries a fresh link, and the old one stops working.

Only the single-gift endpoint refreshes links. GET /v1/gifts and GET /v1/orders return whatever link the gift currently has, which may have expired. Use them for status, and fetch the single gift before sending a link to anyone.

Fixing a failed delivery

When an email bounces or a text can't be delivered, the gift's status becomes failed. Redirect it to a corrected address or number:

curl -X PUT https://api.onme.com/v1/gifts/g-XLotjYqCLoI9pgf0jKYl5gXsNzxkBANTiq1VyivdeRA/delivery \
  -H "Authorization: Bearer $ONME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "method": "email", "email": "sam.lee@example.com" }'

The response is the updated gift, with the new destination and status back to sent. We send the gift to the new destination right away, and the link in the undelivered message stops working.

You can redirect a gift when all of these are true:

• It was sent by email or phone. Link gifts can't be redirected, and a gift can't be switched to link.
• Its status is failed. A gift that was delivered can't be rerouted, even to fix a typo, so that no one can redirect a gift that already reached someone.
• It hasn't been claimed.

You can switch methods while you redirect, from email to SMS or the other way round. Each gift can be redirected up to 10 times.

These errors mean the redirect was refused and nothing changed: