usend Docs
Receiving

Receiving webhook

The email.received event and how to process it.

Each email received on one of your domains triggers an email.received event for every webhook subscribed to it. Subscribe when you create a webhook:

Shell
curl -X POST https://api.usend.et/webhooks \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "endpoint": "https://acme.com/webhooks/usend", "events": ["email.received"] }'

Payload

JSON
{
  "type": "email.received",
  "created_at": "2026-10-11T08:30:12.402Z",
  "data": {
    "email_id": "a39999a6-88e3-48b1-888b-beaabcde1b33",
    "from": "Ann <[email protected]>",
    "to": ["[email protected]"],
    "cc": [],
    "subject": "Question about my order",
    "text": "Hi, where is order #1042?",
    "html": "<p>Hi, where is order #1042?</p>",
    "message_id": "[email protected]",
    "created_at": "2026-10-11T08:30:12Z",
    "attachments": [
      {
        "id": "2a0c9ce0-3112-4728-976e-47ddcd16a318",
        "filename": "screenshot.png",
        "content_type": "image/png",
        "size": 182044
      }
    ]
  }
}
FieldDescription
email_idThe ID of the received email. Use it with the received emails API.
fromThe sender from the From header.
toAddresses from the To header, or the recipients at your domain when the header is missing.
ccAddresses from the Cc header.
subjectThe subject.
text, htmlThe decoded bodies. Either may be empty.
message_idThe Message-ID header of the message, without angle brackets. Useful to thread replies.
created_atWhen usend received the message.
attachmentsMetadata of each attachment. The content is not in the webhook: see Receiving attachments.

The request is signed like every usend webhook. Verify the signature before trusting it.

More details

The webhook carries what most applications need. For everything else, fetch the email:

  • GET /inbound/emails/{id} returns the bodies, cc, reply_to, all headers and the attachments.
  • GET /inbound/emails/{id}/raw returns the original message as message/rfc822, for full MIME parsing.

Tips

  • Respond fast. Return a 2xx as soon as you have stored the event and do the processing in the background. usend retries other responses.
  • Deduplicate. A retry delivers the same event again with the same webhook-id header. Use it, or email_id, to process each message once.
  • Treat content as untrusted. Received email comes from anyone on the internet. Sanitize HTML before you display it.