API docs by Redocly

Firefox Relay API (1.0)

Download OpenAPI specification:

Keep your email safe from hackers and trackers. This API is built with Django REST Framework and powers the Relay website UI, add-on, Firefox browser, and 3rd-party app integrations.

privaterelay

flags_list

Feature flags.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
query Parameters
everyone
boolean
id
integer
name
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

flags_create

Feature flags.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
Request Body schema:
required
name
required
string <= 100 characters

The human/computer readable name.

everyone
boolean or null

Flip this flag on (Yes) or off (No) for everyone, overriding all other settings. Leave as Unknown to use normally.

note
string

Note where this Flag is used.

Responses

Request samples

Content type
{
  • "name": "string",
  • "everyone": true,
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "everyone": true,
  • "note": "string"
}

flags_retrieve

Feature flags.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this Flag.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "everyone": true,
  • "note": "string"
}

flags_partial_update

Feature flags.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this Flag.

Request Body schema:
name
string <= 100 characters

The human/computer readable name.

everyone
boolean or null

Flip this flag on (Yes) or off (No) for everyone, overriding all other settings. Leave as Unknown to use normally.

note
string

Note where this Flag is used.

Responses

Request samples

Content type
{
  • "name": "string",
  • "everyone": true,
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "everyone": true,
  • "note": "string"
}

profiles_list

Relay user extended profile data.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

profiles_create

Relay user extended profile data.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
Request Body schema:
server_storage
boolean
store_phone_log
boolean
onboarding_state
integer <int64> [ 0 .. 9223372036854776000 ]
onboarding_free_state
integer <int64> [ 0 .. 9223372036854776000 ]
remove_level_one_email_trackers
boolean or null

Responses

Request samples

Content type
{
  • "server_storage": true,
  • "store_phone_log": true,
  • "onboarding_state": 9223372036854776000,
  • "onboarding_free_state": 9223372036854776000,
  • "remove_level_one_email_trackers": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "server_storage": true,
  • "store_phone_log": true,
  • "subdomain": "string",
  • "has_premium": true,
  • "has_phone": true,
  • "has_vpn": true,
  • "has_megabundle": true,
  • "onboarding_state": 9223372036854776000,
  • "onboarding_free_state": 9223372036854776000,
  • "date_phone_registered": "2019-08-24T14:15:22Z",
  • "date_subscribed": "2019-08-24T14:15:22Z",
  • "avatar": "string",
  • "next_email_try": "2019-08-24T14:15:22Z",
  • "bounce_status": {
    },
  • "api_token": "2551c122-8b7f-416d-85cb-7f37a24c74b1",
  • "emails_blocked": 0,
  • "emails_forwarded": 0,
  • "emails_replied": 0,
  • "level_one_trackers_blocked": 0,
  • "remove_level_one_email_trackers": true,
  • "total_masks": 0,
  • "at_mask_limit": true,
  • "metrics_enabled": true
}

profiles_retrieve

Relay user extended profile data.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this profile.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "server_storage": true,
  • "store_phone_log": true,
  • "subdomain": "string",
  • "has_premium": true,
  • "has_phone": true,
  • "has_vpn": true,
  • "has_megabundle": true,
  • "onboarding_state": 9223372036854776000,
  • "onboarding_free_state": 9223372036854776000,
  • "date_phone_registered": "2019-08-24T14:15:22Z",
  • "date_subscribed": "2019-08-24T14:15:22Z",
  • "avatar": "string",
  • "next_email_try": "2019-08-24T14:15:22Z",
  • "bounce_status": {
    },
  • "api_token": "2551c122-8b7f-416d-85cb-7f37a24c74b1",
  • "emails_blocked": 0,
  • "emails_forwarded": 0,
  • "emails_replied": 0,
  • "level_one_trackers_blocked": 0,
  • "remove_level_one_email_trackers": true,
  • "total_masks": 0,
  • "at_mask_limit": true,
  • "metrics_enabled": true
}

profiles_update

Relay user extended profile data.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this profile.

Request Body schema:
server_storage
boolean
store_phone_log
boolean
onboarding_state
integer <int64> [ 0 .. 9223372036854776000 ]
onboarding_free_state
integer <int64> [ 0 .. 9223372036854776000 ]
remove_level_one_email_trackers
boolean or null

Responses

Request samples

Content type
{
  • "server_storage": true,
  • "store_phone_log": true,
  • "onboarding_state": 9223372036854776000,
  • "onboarding_free_state": 9223372036854776000,
  • "remove_level_one_email_trackers": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "server_storage": true,
  • "store_phone_log": true,
  • "subdomain": "string",
  • "has_premium": true,
  • "has_phone": true,
  • "has_vpn": true,
  • "has_megabundle": true,
  • "onboarding_state": 9223372036854776000,
  • "onboarding_free_state": 9223372036854776000,
  • "date_phone_registered": "2019-08-24T14:15:22Z",
  • "date_subscribed": "2019-08-24T14:15:22Z",
  • "avatar": "string",
  • "next_email_try": "2019-08-24T14:15:22Z",
  • "bounce_status": {
    },
  • "api_token": "2551c122-8b7f-416d-85cb-7f37a24c74b1",
  • "emails_blocked": 0,
  • "emails_forwarded": 0,
  • "emails_replied": 0,
  • "level_one_trackers_blocked": 0,
  • "remove_level_one_email_trackers": true,
  • "total_masks": 0,
  • "at_mask_limit": true,
  • "metrics_enabled": true
}

profiles_partial_update

Relay user extended profile data.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this profile.

Request Body schema:
server_storage
boolean
store_phone_log
boolean
onboarding_state
integer <int64> [ 0 .. 9223372036854776000 ]
onboarding_free_state
integer <int64> [ 0 .. 9223372036854776000 ]
remove_level_one_email_trackers
boolean or null

Responses

Request samples

Content type
{
  • "server_storage": true,
  • "store_phone_log": true,
  • "onboarding_state": 9223372036854776000,
  • "onboarding_free_state": 9223372036854776000,
  • "remove_level_one_email_trackers": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "server_storage": true,
  • "store_phone_log": true,
  • "subdomain": "string",
  • "has_premium": true,
  • "has_phone": true,
  • "has_vpn": true,
  • "has_megabundle": true,
  • "onboarding_state": 9223372036854776000,
  • "onboarding_free_state": 9223372036854776000,
  • "date_phone_registered": "2019-08-24T14:15:22Z",
  • "date_subscribed": "2019-08-24T14:15:22Z",
  • "avatar": "string",
  • "next_email_try": "2019-08-24T14:15:22Z",
  • "bounce_status": {
    },
  • "api_token": "2551c122-8b7f-416d-85cb-7f37a24c74b1",
  • "emails_blocked": 0,
  • "emails_forwarded": 0,
  • "emails_replied": 0,
  • "level_one_trackers_blocked": 0,
  • "remove_level_one_email_trackers": true,
  • "total_masks": 0,
  • "at_mask_limit": true,
  • "metrics_enabled": true
}

report_webcompat_issue_create

Report a Relay issue from an extension or integration.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
Request Body schema:
required
issue_on_domain
required
string <uri> <= 200 characters
user_agent
string
Default: ""
email_mask_not_accepted
boolean
Default: false
add_on_visual_issue
boolean
Default: false
email_not_received
boolean
Default: false
other_issue
string
Default: ""

Responses

Request samples

Content type
{
  • "issue_on_domain": "https://accounts.firefox.com",
  • "user_agent": "Firefox",
  • "email_mask_not_accepted": true,
  • "add_on_visual_issue": false,
  • "email_not_received": false,
  • "other_issue": ""
}

runtime_data_retrieve

Get data needed to present the Relay dashboard to a visitor or user.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuthNone

Responses

Response samples

Content type
application/json
{
  • "FXA_ORIGIN": "https://accounts.firefox.com",
  • "PERIODICAL_PREMIUM_PRODUCT_ID": "prod_XXXXXXXXXXXXXX",
  • "GOOGLE_ANALYTICS_ID": "UA-########-##",
  • "GA4_MEASUREMENT_ID": "G-XXXXXXXXX",
  • "BUNDLE_PRODUCT_ID": "prod_XXXXXXXXXXXXXX",
  • "MEGABUNDLE_PRODUCT_ID": "prod_XXXXXXXXXXXXXX",
  • "PHONE_PRODUCT_ID": "prod_XXXXXXXXXXXXXX",
  • "PERIODICAL_PREMIUM_PLANS": {
    },
  • "PHONE_PLANS": {
    },
  • "BUNDLE_PLANS": {
    },
  • "MEGABUNDLE_PLANS": {
    },
  • "BASKET_ORIGIN": "https://basket.mozilla.org",
  • "WAFFLE_FLAGS": [
    ],
  • "WAFFLE_SWITCHES": [ ],
  • "WAFFLE_SAMPLES": [ ],
  • "MAX_MINUTES_TO_VERIFY_REAL_PHONE": 5
}

terms_accepted_user_create

Create a Relay user from an FXA token.

See API Auth doc for details.

Authorizations:
None
header Parameters
Authorization
required
string
Examples:
  • Bearer XXXX-ZZZZ - bearer

FXA Bearer Token. Can not be set in browsable API.

Responses

users_list

Relay user data stored in Django user model.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

users_retrieve

Relay user data stored in Django user model.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this user.

Responses

Response samples

Content type
application/json
{
  • "email": "user@example.com"
}

emails

domainaddresses_list

An email address with subdomain chosen by a Relay user.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
query Parameters
address
string
block_list_emails
boolean
created_at
string <date-time>
description
string
domain
integer
Enum: 1 2
  • 1 - RELAY_FIREFOX_DOMAIN
  • 2 - MOZMAIL_DOMAIN
enabled
boolean
id
integer
last_modified_at
string <date-time>
last_used_at
string <date-time>
num_blocked
integer
num_forwarded
integer
num_spam
integer
used_on
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

domainaddresses_create

An email address with subdomain chosen by a Relay user.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
Request Body schema:
required
enabled
boolean
description
string <= 64 characters
block_list_emails
boolean
used_on
string or null
address
required
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
{
  • "enabled": true,
  • "description": "string",
  • "block_list_emails": true,
  • "used_on": "string",
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "mask_type": "custom",
  • "enabled": true,
  • "description": "string",
  • "block_list_emails": true,
  • "used_on": "string",
  • "id": 0,
  • "address": "string",
  • "domain": 1,
  • "full_address": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_modified_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "num_forwarded": 0,
  • "num_blocked": 0,
  • "num_level_one_trackers_blocked": 0,
  • "num_replied": 0,
  • "num_spam": 0
}

domainaddresses_retrieve

An email address with subdomain chosen by a Relay user.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this domain address.

Responses

Response samples

Content type
application/json
{
  • "mask_type": "custom",
  • "enabled": true,
  • "description": "string",
  • "block_list_emails": true,
  • "used_on": "string",
  • "id": 0,
  • "address": "string",
  • "domain": 1,
  • "full_address": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_modified_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "num_forwarded": 0,
  • "num_blocked": 0,
  • "num_level_one_trackers_blocked": 0,
  • "num_replied": 0,
  • "num_spam": 0
}

domainaddresses_update

An email address with subdomain chosen by a Relay user.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this domain address.

Request Body schema:
required
enabled
boolean
description
string <= 64 characters
block_list_emails
boolean
used_on
string or null
address
required
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
{
  • "enabled": true,
  • "description": "string",
  • "block_list_emails": true,
  • "used_on": "string",
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "mask_type": "custom",
  • "enabled": true,
  • "description": "string",
  • "block_list_emails": true,
  • "used_on": "string",
  • "id": 0,
  • "address": "string",
  • "domain": 1,
  • "full_address": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_modified_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "num_forwarded": 0,
  • "num_blocked": 0,
  • "num_level_one_trackers_blocked": 0,
  • "num_replied": 0,
  • "num_spam": 0
}

domainaddresses_partial_update

An email address with subdomain chosen by a Relay user.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this domain address.

Request Body schema:
enabled
boolean
description
string <= 64 characters
block_list_emails
boolean
used_on
string or null
address
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
{
  • "enabled": true,
  • "description": "string",
  • "block_list_emails": true,
  • "used_on": "string",
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "mask_type": "custom",
  • "enabled": true,
  • "description": "string",
  • "block_list_emails": true,
  • "used_on": "string",
  • "id": 0,
  • "address": "string",
  • "domain": 1,
  • "full_address": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_modified_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "num_forwarded": 0,
  • "num_blocked": 0,
  • "num_level_one_trackers_blocked": 0,
  • "num_replied": 0,
  • "num_spam": 0
}

domainaddresses_destroy

An email address with subdomain chosen by a Relay user.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this domain address.

Responses

first_forwarded_email_create

Requires free_user_onboarding flag to be active for the user.

Send the first_forwarded_email.html email to the user via a mask. See /emails/first_forwarded_email.

Note: mask value must be a RelayAddress that belongs to the authenticated user. A DomainAddress will not work.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
Request Body schema:
required
mask
required
string <email>

Responses

Request samples

Content type
{
  • "mask": "user@example.com"
}

relayaddresses_list

An email address with a random name provided by Relay.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
query Parameters
address
string
block_list_emails
boolean
created_at
string <date-time>
description
string
domain
integer
Enum: 1 2
  • 1 - RELAY_FIREFOX_DOMAIN
  • 2 - MOZMAIL_DOMAIN
enabled
boolean
generated_for
string
id
integer
last_modified_at
string <date-time>
last_used_at
string <date-time>
num_blocked
integer
num_forwarded
integer
num_spam
integer
used_on
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

relayaddresses_create

An email address with a random name provided by Relay.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
Request Body schema:
enabled
boolean
description
string <= 64 characters
generated_for
string <= 255 characters
block_list_emails
boolean
used_on
string or null

Responses

Request samples

Content type
{
  • "enabled": true,
  • "description": "string",
  • "generated_for": "string",
  • "block_list_emails": true,
  • "used_on": "string"
}

Response samples

Content type
application/json
{
  • "mask_type": "random",
  • "enabled": true,
  • "description": "string",
  • "generated_for": "string",
  • "block_list_emails": true,
  • "used_on": "string",
  • "id": 0,
  • "address": "string",
  • "domain": 1,
  • "full_address": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_modified_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "num_forwarded": 0,
  • "num_blocked": 0,
  • "num_level_one_trackers_blocked": 0,
  • "num_replied": 0,
  • "num_spam": 0
}

relayaddresses_retrieve

An email address with a random name provided by Relay.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this relay address.

Responses

Response samples

Content type
application/json
{
  • "mask_type": "random",
  • "enabled": true,
  • "description": "string",
  • "generated_for": "string",
  • "block_list_emails": true,
  • "used_on": "string",
  • "id": 0,
  • "address": "string",
  • "domain": 1,
  • "full_address": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_modified_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "num_forwarded": 0,
  • "num_blocked": 0,
  • "num_level_one_trackers_blocked": 0,
  • "num_replied": 0,
  • "num_spam": 0
}

relayaddresses_update

An email address with a random name provided by Relay.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this relay address.

Request Body schema:
enabled
boolean
description
string <= 64 characters
generated_for
string <= 255 characters
block_list_emails
boolean
used_on
string or null

Responses

Request samples

Content type
{
  • "enabled": true,
  • "description": "string",
  • "generated_for": "string",
  • "block_list_emails": true,
  • "used_on": "string"
}

Response samples

Content type
application/json
{
  • "mask_type": "random",
  • "enabled": true,
  • "description": "string",
  • "generated_for": "string",
  • "block_list_emails": true,
  • "used_on": "string",
  • "id": 0,
  • "address": "string",
  • "domain": 1,
  • "full_address": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_modified_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "num_forwarded": 0,
  • "num_blocked": 0,
  • "num_level_one_trackers_blocked": 0,
  • "num_replied": 0,
  • "num_spam": 0
}

relayaddresses_partial_update

An email address with a random name provided by Relay.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this relay address.

Request Body schema:
enabled
boolean
description
string <= 64 characters
generated_for
string <= 255 characters
block_list_emails
boolean
used_on
string or null

Responses

Request samples

Content type
{
  • "enabled": true,
  • "description": "string",
  • "generated_for": "string",
  • "block_list_emails": true,
  • "used_on": "string"
}

Response samples

Content type
application/json
{
  • "mask_type": "random",
  • "enabled": true,
  • "description": "string",
  • "generated_for": "string",
  • "block_list_emails": true,
  • "used_on": "string",
  • "id": 0,
  • "address": "string",
  • "domain": 1,
  • "full_address": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_modified_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "num_forwarded": 0,
  • "num_blocked": 0,
  • "num_level_one_trackers_blocked": 0,
  • "num_replied": 0,
  • "num_spam": 0
}

relayaddresses_destroy

An email address with a random name provided by Relay.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this relay address.

Responses

phones

inboundcontact_list

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

inboundcontact_retrieve

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this inbound contact.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "relay_number": 0,
  • "inbound_number": "string",
  • "last_inbound_date": "2019-08-24T14:15:22Z",
  • "last_inbound_type": "call",
  • "num_calls": 0,
  • "num_calls_blocked": 0,
  • "last_call_date": "2019-08-24T14:15:22Z",
  • "num_texts": 0,
  • "num_texts_blocked": 0,
  • "last_text_date": "2019-08-24T14:15:22Z",
  • "blocked": true
}

inboundcontact_partial_update

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this inbound contact.

Request Body schema:
blocked
boolean

Responses

Request samples

Content type
{
  • "blocked": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "relay_number": 0,
  • "inbound_number": "string",
  • "last_inbound_date": "2019-08-24T14:15:22Z",
  • "last_inbound_type": "call",
  • "num_calls": 0,
  • "num_calls_blocked": 0,
  • "last_call_date": "2019-08-24T14:15:22Z",
  • "num_texts": 0,
  • "num_texts_blocked": 0,
  • "last_text_date": "2019-08-24T14:15:22Z",
  • "blocked": true
}

realphone_list

Get real phone number records for the authenticated user.

The authenticated user must have a subscription that grants one of the SUBSCRIPTIONS_WITH_PHONE capabilities.

Client must be authenticated, and these endpoints only return data that is "owned" by the authenticated user.

All endpoints are rate-limited to settings.PHONE_RATE_LIMIT

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

realphone_create

Add real phone number to the authenticated user.

The "flow" to verify a real phone number is:

  1. POST a number (Will text a verification code to the number) 2a. PATCH the verification code to the realphone/{id} endpoint 2b. POST the number and verification code together

The authenticated user must have a subscription that grants one of the SUBSCRIPTIONS_WITH_PHONE capabilities.

The number field should be in E.164 format which includes a country code. If the number is not in E.164 format, this endpoint will try to create an E.164 number by prepending the country code of the client making the request (i.e., from the X-Client-Region HTTP header).

If the POST does NOT include a verification_code and the number is a valid (currently, US-based) number, this endpoint will text a verification code to the number.

If the POST DOES include a verification_code, and the code matches a code already sent to the number, this endpoint will set verified to True for this number.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
Request Body schema:
required
number
required
string <= 15 characters
verification_code
string <= 8 characters

Responses

Request samples

Content type
{
  • "number": "string",
  • "verification_code": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "number": "string",
  • "verification_sent_date": "2019-08-24T14:15:22Z",
  • "verified": false,
  • "verified_date": "2019-08-24T14:15:22Z",
  • "country_code": "string"
}

realphone_retrieve

Get real phone number records for the authenticated user.

The authenticated user must have a subscription that grants one of the SUBSCRIPTIONS_WITH_PHONE capabilities.

Client must be authenticated, and these endpoints only return data that is "owned" by the authenticated user.

All endpoints are rate-limited to settings.PHONE_RATE_LIMIT

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this real phone.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "number": "string",
  • "verification_sent_date": "2019-08-24T14:15:22Z",
  • "verified": false,
  • "verified_date": "2019-08-24T14:15:22Z",
  • "country_code": "string"
}

realphone_partial_update

Update the authenticated user's real phone number.

The authenticated user must have a subscription that grants one of the SUBSCRIPTIONS_WITH_PHONE capabilities.

The {id} should match a previously-POSTed resource that belongs to the user.

The number field should be in E.164 format which includes a country code.

The verification_code should be the code that was texted to the number during the POST. If it matches, this endpoint will set verified to True for this number.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this real phone.

Request Body schema:
number
string <= 15 characters
verification_code
string <= 8 characters

Responses

Request samples

Content type
{
  • "number": "string",
  • "verification_code": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "number": "string",
  • "verification_sent_date": "2019-08-24T14:15:22Z",
  • "verified": false,
  • "verified_date": "2019-08-24T14:15:22Z",
  • "country_code": "string"
}

realphone_destroy

Delete a real phone resource.

Only un-verified real phone resources can be deleted.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this real phone.

Responses

realphone_resend_welcome_sms_create

Resend the "Welcome" SMS, including vCard.

Requires the user to be signed in and to have phone service.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth

Responses

Response samples

Content type
application/json
{
  • "msg": "sent"
}

relaynumber_list

ModelViewSet mixin for creating object for the authenticated user.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

relaynumber_create

Provision a phone number with Twilio and assign to the authenticated user.

⚠️ THIS WILL BUY A PHONE NUMBER ⚠️ If you have real account credentials in your TWILIO_* env vars, this will really provision a Twilio number to your account. You can use Test Credentials to call this endpoint without making a real phone number purchase. If you do, you need to pass one of the test phone numbers.

The number should be in E.164 format.

Every call or text to the relay number will be sent as a webhook to the URL configured for your TWILIO_SMS_APPLICATION_SID.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
Request Body schema:
required
number
required
string <= 15 characters
enabled
boolean

Responses

Request samples

Content type
{
  • "number": "string",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "number": "string",
  • "location": "string",
  • "country_code": "string",
  • "enabled": true,
  • "remaining_minutes": 0,
  • "remaining_texts": 0,
  • "calls_forwarded": 0,
  • "calls_blocked": 0,
  • "texts_forwarded": 0,
  • "texts_blocked": 0,
  • "calls_and_texts_forwarded": 0,
  • "calls_and_texts_blocked": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

relaynumber_retrieve

ModelViewSet mixin for creating object for the authenticated user.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this relay number.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "number": "string",
  • "location": "string",
  • "country_code": "string",
  • "enabled": true,
  • "remaining_minutes": 0,
  • "remaining_texts": 0,
  • "calls_forwarded": 0,
  • "calls_blocked": 0,
  • "texts_forwarded": 0,
  • "texts_blocked": 0,
  • "calls_and_texts_forwarded": 0,
  • "calls_and_texts_blocked": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

relaynumber_partial_update

Update the authenticated user's relay number.

The authenticated user must have a subscription that grants one of the SUBSCRIPTIONS_WITH_PHONE capabilities.

The {id} should match a previously-POSTed resource that belongs to the authenticated user.

This is primarily used to toggle the enabled field.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
path Parameters
id
required
integer

A unique integer value identifying this relay number.

Request Body schema:
number
string <= 15 characters
enabled
boolean

Responses

Request samples

Content type
{
  • "number": "string",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "number": "string",
  • "location": "string",
  • "country_code": "string",
  • "enabled": true,
  • "remaining_minutes": 0,
  • "remaining_texts": 0,
  • "calls_forwarded": 0,
  • "calls_blocked": 0,
  • "texts_forwarded": 0,
  • "texts_blocked": 0,
  • "calls_and_texts_forwarded": 0,
  • "calls_and_texts_blocked": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

relaynumber_search_retrieve

Search for available numbers.

This endpoints uses the underlying AvailablePhoneNumbers API.

Accepted query params:

  • ?location=
    • Will be passed to AvailablePhoneNumbers in_locality param
  • ?area_code=
    • Will be passed to AvailablePhoneNumbers area_code param
Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
query Parameters
area_code
string
Examples:
  • area_code=918 - Tulsa OK USA
location
string
Examples:
  • location=Miami - Miami FL USA

Responses

Response samples

Content type
application/json
[
  • {
    }
]

relaynumber_suggestions_retrieve

Returns suggested relay numbers for the authenticated user.

Based on the user's real number, returns available relay numbers:

  • same_prefix_options: Numbers that match as much of the user's real number as possible.
  • other_areas_options: Numbers that exactly match the user's real number, in a different area code.
  • same_area_options: Other numbers in the same area code as the user.
  • random_options: Available numbers in the user's country
Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth

Responses

Response samples

Content type
application/json
{
  • "real_num": "4045556789",
  • "same_prefix_options": [ ],
  • "other_areas_options": [ ],
  • "same_area_options": [ ],
  • "random_options": [
    ]
}

vCard_retrieve

Get a Relay vCard. lookup_key should be passed in url path.

We use this to return a vCard for a number. When we create a RelayNumber, we create a secret lookup_key and text it to the user.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuthNone
path Parameters
lookup_key
required
string

Responses

Response samples

Content type
text/x-vcard
BEGIN:VCARD
VERSION:3.0
FN:Firefox Relay
TEL:+14045555555
END:VCARD

phones: Twilio

inbound_call_create

Handle an inbound call request sent by Twilio.

The return value is TwilML Response XML that reports the error or instructs Twilio to connect the callers.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuthNone
header Parameters
X-Twilio-Signature
required
string
Request Body schema:
required
Caller
required
string
Called
required
string

Responses

Request samples

Content type
{
  • "Caller": "+13035556789",
  • "Called": "+14045556789"
}

Response samples

Content type
text/xml
{
  "say": "Sorry, that number is not available."
}

inbound_sms_create

Handle an inbound SMS message sent by Twilio.

The return value is TwilML Response XML that reports the error or an empty success message.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuthNone
header Parameters
X-Twilio-Signature
required
string
Request Body schema:
required
text
required
string
to
required
string
from
required
string

Responses

Request samples

Content type
{
  • "to": "+13035556789",
  • "from": "+14045556789",
  • "text": "Hello!"
}

Response samples

Content type
text/xml
null

sms_status_create

Twilio callback for SMS status.

When the message is delivered, this calls Twilio to delete the message from logs.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuthNone
header Parameters
X-Twilio-Signature
required
string
Request Body schema:
required
SmsStatus
required
string
MessageSid
required
string

Responses

Request samples

Content type
{
  • "SmsStatus": "delivered",
  • "MessageSid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

voice_status_create

Twilio callback for voice call status.

When the call is complete, the user's remaining monthly time is updated, and the call is deleted from Twilio logs.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuthNone
header Parameters
X-Twilio-Signature
required
string
Request Body schema:
required
CallSid
required
string
Called
required
string
CallStatus
required
string
CallDuration
integer

Responses

Request samples

Content type
{
  • "CallSid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "Called": "+14045556789",
  • "CallStatus": "completed",
  • "CallDuration": 127
}

phones: Outbound

call_create

Make a call from the authenticated user's relay number.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
Request Body schema:
required
to
required
string

Responses

Request samples

Content type
{
  • "to": "+13035556789"
}

message_create

Send a message from the user's relay number.

POST params: body: the body of the message destination: E.164-formatted phone number

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
Request Body schema:
required
body
required
string
destination
required
string

Responses

Request samples

Content type
{
  • "body": "Hello!",
  • "destination": "+13045554567"
}

messages_retrieve

Get the user's SMS messages sent to or from the phone mask

Pass ?with=<E.164> parameter to filter the messages to only the ones sent between the phone mask and the <E.164> number.

Pass ?direction=inbound|outbound to filter the messages to only the inbound or outbound messages. If omitted, return both.

Authorizations:
Mozilla account Token AuthtokenAuthcookieAuth
query Parameters
direction
string
Enum: "inbound" "outbound"

filter to inbound or outbound messages

with
string

filter to messages with the given E.164 number

Responses

Response samples

Content type
application/json
[
  • {
    }
]