Docs: Email Address Management

Reading

Endpoint

https://api.gocarrot.com/v2/email

Request Type

GET

Rate Limiting

300 requests per second

Description: The GET v2/email endpoint retrieves the current email address for a game assigned player id.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

user_id

The Game Assigned Player ID of the player you are retrieving the email address for. This must match the value provided by the game client’s Teak SDK integration.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status' and 'email' keys. 'status' will be 'ok' and 'email' will either be the player’s email address or null if the player has no email address in Teak.

Example

{"status":"ok", "email":"eve@example.com"}

Error Responses

Not Found

Status Code

404

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary containing keys indicating which resources were not found, with values being an array of human readable error messages.

Example

{"status":"error","errors":{"user_id":["No player with id foo"]}}

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["/v2/email may only be called 300 times per second. Please wait a second and try again"]}}

Reading Subscription Status

Endpoint

https://api.gocarrot.com/v2/email/subscription_status

Request Type

GET

Rate Limiting

300 requests per second

Description: The GET v2/email/subscription_status endpoint retrieves the current subscription status and delivery fault flag for a given email address.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

email

An email address.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'channel', 'state', 'delivery_fault', 'email', and 'categories' keys.

status

'ok'

channel

'email'

state

One of 'spam_report', opt_out', 'available', or 'opt_in'.
'spam_report' indicates that the address has marked a delivered email as spam and is opted out from future deliveries.
'opt_out' indicates that the address has unsubscribed from emails.
'available' indicates the address can be sent to, but has not confirmed an opt in.
'opt_in' indicates that the address has confirmed an opt in to receiving emails.

delivery_fault

true if an error was encountered attempting to send to the email address, otherwise false

email

The email address the subscription state was retrieved for.

Error Responses

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["/v2/email/subscription_status may only be called 300 times per second. Please wait a second and try again"]}}

Retrieving Recent Unsubscriptions

Endpoint

https://api.gocarrot.com/v2/email/unsubscriptions

Request Type

GET

Rate Limiting

50 requests per second

Description: The GET v2/email/unsubscriptions endpoint retrieves a list of email addresses that have opted out since the given timestamp.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

since

An ISO 8601 timestamp. Only email addresses that have opted out since this time will be returned. Example: 2020-01-01T00:00:00Z

Optional Parameters

limit

The number of recent unsubs to return. Will be clamped to [1, 10000]. Defaults to 1,000

after

A pagination token from a previous call to v2/email/unsubscriptions

Success Response

Status Code

200

Response Body

JSON dictionary with 'status', and 'opt_outs' keys.

status

'ok'

opt_outs

A list of maps with the keys 'device_key', 'updated_at', and 'reason'.

paging

JSON dictonary with 'cursors' and 'next' keys.
'cursors' will be a dictionary containing an 'after' key, whose value can be passed as the 'after' parameter to v2/email/unsubscriptions to retrieve the next page.
'next' will be the full path and non-authorization query parameters to retrieve the next page.

Example

{
  "status":"ok",
  "opt_outs": [
    {"device_key": "john.smith@gmail.com", "updated_at": "2024-09-01T12:34:56Z", "reason": "opt_out"},
    {"device_key": "jane.doe@gmail.com", "updated_at": "2024-09-01T12:34:56Z", "reason": "spam_report"}
  ],
  "paging": {
    "cursors": {"after": "MTU="},
    "next": "/v2/email/unsubscriptions?limit=1&after=MTU="
  }
}

Error Responses

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["/v2/email/unsubscriptions may only be called 50 times per second. Please wait a second and try again"]}}

Updating

Endpoint

https://api.gocarrot.com/v2/email

Request Type

POST

Content-Type

application/json or application/x-www-form-urlencoded

Rate Limiting

300 requests per second

Description: The v2/email endpoint allows for server side modification of player email addresses. For example, this API can be connected to your internal administrative tools to ensure that the email address Teak has on file for a player is promptly updated in response to any modifications made in your internal administrative tools.

Please be aware that Teak enforces that each player may only have a single email address, and each email address may only belong to a single player. The response to this API will inform you of the actions Teak took in order to preserve these invariants while making the requested change.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

user_id

The Game Assigned Player ID of the player you are updating the email address for. This must match the value provided by the game client’s Teak SDK integration.

email

The email address to assign to this player.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status' and 'action' keys. 'status' will be 'ok'. 'action' will be one of 'moved_and_changed', 'moved', 'changed', 'added', or 'none', depending on the action taken to update the email address for the player.

Example

{"status": "ok", "action": "added"}

Email Changed Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'action', and 'previous_email' keys. 'action' will be 'changed', and 'previous_email' will be the email address previously on file for the user before this API call.

Example

{"status":"ok", "action":"changed", "previous_email":"foo@example.com"}

Email Moved Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'action', and 'previous_player_ids' keys. 'action' will be 'moved', and 'previous_player_ids' will be an array of strings of all the game assigned player ids Teak has associated with the internal player record that previously had the given email address.

Example

{"status":"ok", "action":"moved", "previous_player_ids":["abc", "def"]}

Email Moved And Changed Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'action', 'previous_email', and 'previous_player_ids' keys. 'action' will be 'moved_and_changed', 'previous_email' will be the email address previously on file for the user before this API call, and 'previous_player_ids' will be an array of strings of all the game assigned player ids Teak has associated with the internal player record that previously had the given email address.

Example

{"status":"ok", "action":"moved_and_changed", "previous_email":"foo@example.com", "previous_player_ids":["abc", "def"]}

Error Responses

Player under an Exclusion

Status Code

422

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary containing keys indicating which resources were not found, with values being an array of human readable error messages.

Example

{"status":"error","errors":{"user_id":["player42 is excluded from marketing communication"]}}

Not Found

Status Code

404

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary containing keys indicating which resources were not found, with values being an array of human readable error messages.

Example

{"status":"error","errors":{"user_id":["No player with id foo"]}}

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["/v2/email may only be called 300 times per second. Please wait a second and try again"]}}

Updating Subscription Status

Endpoint

https://api.gocarrot.com/v2/email/subscription_status

Request Type

POST

Content-Type

application/json or application/x-www-form-urlencoded

Rate Limiting

300 requests per second

Description: The POST v2/email/subscription_status endpoint updates the current subscription status for a given email address.

It is not necessary for Teak to have previously seen the given email address for the game. Changes made to email addresses not previously seen will apply to the address as soon as it is associated with a player.

Updating subscription status will not clear any delivery faults. See Clear Delivery Fault to clear a delivery fault.

Requests to update a spam_report state to opt_out will be ignored.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

email

An email address.

state

One of 'opt_out', 'available', or 'opt_in'

opt_out

No emails should be sent to this email address.

available

Emails may be sent to this email address, however it has not confirmed an opt in (also known as double opt in)

opt_in

Emails may be sent to this email address and it has confirmed that it wishes to recieve emails (also known as double opt in)

Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'channel', 'state', 'previous_state', 'delivery_fault', 'email', and 'categories' keys.

status

'ok'

channel

'email'

previous_state

The previous subscription status state for this email address. One of 'spam_report', 'opt_out', 'available', or 'opt_in'

state

The newly set state. One of 'spam_report', 'opt_out', 'available', or 'opt_in'

delivery_fault

true if an error was encountered attempting to send to the email address, otherwise false

email

The email address the subscription state was updated for.

Error Responses

Unknown State

Status Code

404

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary containing keys indicating which parameters were invalid, with values being an array of human readable error messages..

Example

{"status":"error","errors":{"state":["Unknown state opted_in"]}}

Invalid email address

Status Code

422

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary containing keys indicating which parameters were invalid, with values being an array of human readable error messages.

Example

{"status":"error","errors":{"email":["Must be a valid email address"]}}

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["/v2/email/subscription_status may only be called 300 times per second. Please wait a second and try again"]}}

Updating Category Subscription Status

Endpoint

https://api.gocarrot.com/v2/email/subscription_status/:category_identifier

Request Type

POST

Content-Type

application/json or application/x-www-form-urlencoded

Rate Limiting

300 requests per second

Description: The POST v2/email/subscription_status/:category_identifier endpoint updates the current subscription status for a given email address and Opt Out Category.

It is not necessary for Teak to have previously seen the given email address for the game. Changes made to email addresses not previously seen will apply to the address as soon as it is associated with a player.

Required Parameters

category_identifier

Note that this is a path parameter. The identifier of the opt out category the email’s subscription status is being updated for.

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

email

An email address.

state

One of 'opt_out' or 'opt_in'

opt_out

No emails should be sent to this email address for this Opt Out Category.

opt_in

Emails may be sent to this email address for this Opt Out Category.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'channel', 'state', 'previous_state', 'delivery_fault', 'email', and 'category' keys.

status

'ok'

channel

'email'

previous_state

The previous subscription status state for this email address and Opt Oute Category. One of 'opt_out' or 'opt_in'

state

The newly set state. One of 'opt_out' or 'opt_in'

delivery_fault

true if an error was encountered attempting to send to the email address, otherwise false

email

The email address the subscription state was updated for.

Error Responses

Unknown State

Status Code

404

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary containing keys indicating which parameters were invalid, with values being an array of human readable error messages..

Example

{"status":"error","errors":{"state":["Unknown state opted_in"]}}

Invalid email address

Status Code

422

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary containing keys indicating which parameters were invalid, with values being an array of human readable error messages.

Example

{"status":"error","errors":{"email":["Must be a valid email address"]}}

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["/v2/email/subscription_status/:category_identifier may only be called 300 times per second. Please wait a second and try again"]}}

Clear Delivery Fault

Endpoint

https://api.gocarrot.com/v2/email/delivery_fault

Request Type

DELETE

Content-Type

application/json or application/x-www-form-urlencoded

Rate Limiting

300 requests per second

Description: The DELETE v2/email/delivery_fault endpoint clears the delivery fault flag for a given email address.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

email

The email address the subscription state was updated for.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status' and 'email' keys.

status

'ok'

email

The email address the subscription state was updated for.

Example

{"status":"ok", "email":"eve@example.com"}

Error Responses

Invalid email address

Status Code

422

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary containing keys indicating which parameters were invalid, with values being an array of human readable error messages.

Example

{"status":"error","errors":{"email":["Must be a valid email address"]}}

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["/v2/email/delivery_fault may only be called 300 times per second. Please wait a second and try again"]}}

Removing

Endpoint

https://api.gocarrot.com/v2/email

Request Type

DELETE

Content-Type

application/json or application/x-www-form-urlencoded

Rate Limiting

300 requests per second

Description: The DELETE v2/email endpoint allows for removal of an email address from a player record in Teak. Teak will retain the subscription status for removed email addresses, and if the email is later readded the previous subscriptoin status will apply.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

user_id

The Game Assigned Player ID of the player you are updating the email address for. This must match the value provided by the game client’s Teak SDK integration.

Email Removed Success Response

Status Code

200

Response Body

JSON dictionary with 'status' and 'action' keys. 'status' will be 'ok' and 'action' will be 'removed'.

Example

{"status":"ok", "action":"removed"}

Email Already Absent Success Response

Status Code

200

Response Body

JSON dictionary with 'status' and 'action' keys. 'status' will be 'ok' and 'action' will be 'none'.

Example

{"status":"ok", "action":"none"}

Error Responses

Not Found

Status Code

404

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary containing keys indicating which resources were not found, with values being an array of human readable error messages.

Example

{"status":"error","errors":{"user_id":["No player with id foo"]}}

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["/v2/email may only be called 300 times per second. Please wait a second and try again"]}}