Skip to content
Roamex API

Email an eSIM

POST
/esims/fulfill
curl --request POST \
  --url https://api.roamex.com/v1/esims/fulfill \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "esimId": "00000000-0000-4000-8000-0000000000c1", "email": "traveller@example.com", "name": "Sam Example", "language": "nl" }'

Emails an eSIM’s QR code and install details to a traveller, with your branding. Calling it again for the same eSIM resends it, to the same or another address. After 20 sends of one eSIM further calls are refused with 429 FULFILL_LIMIT_REACHED, which does not clear with time.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
esimId
required
string format: uuid
email
required

The traveller’s address. Trimmed and lower-cased.

string format: email
<= 254 characters
name

The traveller’s full name. The first word is the first name and the rest the last name; each may be up to 100 characters.

string
firstName

Used together with lastName instead of name when both are set.

string
<= 100 characters
lastName
string
<= 100 characters
language

Email language: en, nl, es, de, it, fr, pl, pt, tr, el, cs or ro. A regional tag such as de-DE uses its base language. Any other value sends in English.

string
default: en

Example 

{
  "esimId": "00000000-0000-4000-8000-0000000000c1",
  "email": "traveller@example.com",
  "name": "Sam Example",
  "language": "nl"
}

Responses

Section titled “Responses”

200

Section titled “200”

The email was sent.

Media typeapplication/json
object
success
required
boolean
fulfilled
required
boolean
isResend
required

true when this eSIM had been sent before.

boolean
recipient
required
object
email
required
string
name
required

Empty when no name was given.

string
statusPageUrl
required

The traveller’s status page for this eSIM.

string | null format: uri
message
required
string

Example 

{
  "success": true,
  "fulfilled": true,
  "isResend": false,
  "recipient": {
    "email": "traveller@example.com",
    "name": "Sam Example"
  },
  "statusPageUrl": "https://roamex.com/esim/example-status-token",
  "message": "eSIM sent successfully to traveller@example.com"
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer

Calls allowed per minute for this endpoint group.

X-RateLimit-Remaining
integer

Calls left in the current minute.

X-RateLimit-Reset
integer

When the current window ends, in Unix seconds.

400

Section titled “400”
  • INVALID_JSON: the body is missing or not a JSON object.
  • MISSING_ESIM_ID: esimId is missing or not a string.
  • MISSING_EMAIL: email is missing or not a string.
  • INVALID_EMAIL: email is not a valid address or is longer than 254 characters.
  • INVALID_NAME: the first or last name is longer than 100 characters.
  • ESIM_CANCELLED: the eSIM is cancelled.
  • ESIM_NOT_READY: the eSIM is not provisioned yet. Wait and try again.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

401

Section titled “401”

AUTH_ERROR: the key is missing, malformed, unknown or revoked. The message says which, for example Missing Authorization header, Invalid Authorization header format. Use: Bearer <api_key>, Invalid API key format or Invalid API key.

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false,
  "error": {
    "code": "AUTH_ERROR",
    "message": "Invalid API key"
  }
}

403

Section titled “403”

AUTH_ERROR: the account is suspended (Your account is suspended. Please contact support.) or rejected (Account is not approved for API access).

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

404

Section titled “404”
  • ESIM_NOT_FOUND: no eSIM with this id belongs to your account.
  • NOT_FOUND: the API is switched off on the platform.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

409

Section titled “409”
  • ESIM_EXPIRED: the eSIM has expired and its install code no longer works.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

413

Section titled “413”

PAYLOAD_TOO_LARGE: the Content-Length header is over 100 KB.

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

429

Section titled “429”

Branch on the code, not on the status.

  • FULFILL_LIMIT_REACHED: this eSIM has been sent 20 times. This does not clear with time; do not retry.
  • RATE_LIMITED: see the shared errors.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.

500

Section titled “500”
  • EMAIL_FAILED: the email was not sent. The message says whether the attempt counts against the 20 sends.
  • FULFILL_FAILED: the send could not be processed.
  • INTERNAL_ERROR, or AUTH_ERROR with status 500: see the shared errors.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

503

Section titled “503”
  • ESIM_NOT_READY: the eSIM’s install data could not be retrieved just now. Nothing was sent. Retry with backoff.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}