Skip to main content

Email API

These instructions describe how to send emails using InTarget Email API

Use the InTarget Email API to create templates, send emails programmatically, manage multilingual translations, and pull delivery statistics.

Contact [email protected] to get your access token. All requests use access-token as a query parameter.

Make sure you comply with InTarget's Bounce and Complaint Policies. Sending may be suspended if your bounce rate reaches 5% or your complaint rate reaches 0.05%.

Basic Recommendations

  1. Implement a double opt-in strategy. When a user signs up, send a confirmation email before adding them to any list. This reduces hard bounces from typos.

  2. Validate email addresses at the point of collection — basic format validation on form submission catches most bad addresses early.

Create an Email Template

POST https://api.intarget.app/rest/email-template/create?access-token=<TOKEN>
{
  "title": "Welcome Email",
  "content": "Hello {{ unsubscribeUrl }}"
}

  • title — template title — required

  • content — HTML content for the template — required

Every template must include the {{ unsubscribeUrl }} variable.

Before placing HTML into the JSON content field, encode it to escape special characters. You can use a tool like freeformatter.com/json-escape.html.

Response:

{"id": 977}

Save the returned id — you'll need it to send emails and manage translations.

Update an Email Template

Use PUT to replace the template entirely, or PATCH to update only the fields you include.

PUT https://api.intarget.app/rest/email-template/update?id=<id>&access-token=<TOKEN>
PATCH https://api.intarget.app/rest/email-template/update?id=<id>&access-token=<TOKEN>

  • PUT — replaces the full template resource with the data you provide

  • PATCH — applies partial changes; fields you omit stay unchanged

Response:

{"id": 977}

Send an Email

POST https://api.intarget.app/v2/messages/email?access-token=<TOKEN>

Send an email either from a saved template or with an inline HTML body. Pick one — templateId and html are mutually exclusive.

{
  "payload": {
    "templateId": null,
    "html": null,
    "subject": null
  },
  "recipient": {
    "playerId": null,
    "address": "[email protected]"
  },
  "category": "promotional",
  "providerId": null,
  "variables": [],
  "internalName": null,
  "idempotencyKey": null
}

payload

  • templateId — integer, greater than 0 — the email template to render. Mutually exclusive with html. Default null.

  • html — string — inline body. Mutually exclusive with templateId. Must contain the unsubscribeUrl variable. Default null.

  • subject — string, up to 255 characters — subject line. Required when you send html. Default null.

recipient

  • playerId — string, up to 255 characters — the player the message is addressed to. Default null.

  • address — string, up to 255 characters — the recipient's email address.

Other Fields

  • category — message category. One of promotional or transactional.

  • providerId — integer, greater than 0 — the provider that sends the message. If empty, the project's default provider is used. Default null.

  • variables — object with string values — external template variables, for example {"topUpValue": "20.00 €"}.

  • internalName — string, up to 255 characters — your own label, kept with the send record. Default null.

  • idempotencyKey — string, up to 255 characters — a caller-side key that makes a repeated send return the first result instead of sending again. Required for transactional messages. Default null.

Example

POST https://api.intarget.app/v2/messages/email?access-token=<TOKEN>
Content-Type: application/json
{
  "payload": {
    "html": "✅ {{ firstName|default('Friend') }}, Funds have been deposited {{ topUpValue }} {{ unsubscribeUrl }}",
    "subject": "✅ {{ firstName|default('Friend') }}, Funds have been deposited {{ topUpValue }}"
  },
  "recipient": {
    "playerId": "2023022617000",
    "address": "[email protected]"
  },
  "category": "transactional",
  "providerId": 17,
  "variables": {
    "topUpValue": "20.00 €"
  },
  "internalName": "Test Email",
  "idempotencyKey": "7c95edc7-457a-40f4-b951-b3f05a2e62d2"
}

Responses

202 — the message is accepted and queued for sending.

{
  "id": "01a042e6-3684-72db-83e6-bf5dd79cfe02",
  "channel": "email",
  "status": "queued"
}

  • 401 — API token missing or invalid.

  • 403 — the API token is not allowed to perform this action.

  • 422 — request validation failed.

Naming Tips

  • Treat internalName as a stable machine identifier — welcome-series-step-1, reactivation-30d — not a human-readable title. It's much easier to group in statistics that way.

  • Keep the name consistent across every send in the same scenario. If it differs, the sends won't merge into a single metric.

Things to Know

  • Variables work in both subject and html.

  • Generate a fresh idempotencyKey per logical event — a UUID works well. If your service retries the same password reset or deposit confirmation, the player still gets exactly one email.

If you pass recipient.playerId, InTarget's standard player variables resolve automatically in both the subject and the body. Use variables only for values that don't live in the player profile — like an order total or a one-time code.

When you send an inline html body, it must contain the unsubscribeUrl variable.

Send an Email — Legacy Endpoint

This endpoint is legacy. Use POST /v2/messages/email above for all new integrations.

POST https://api.intarget.app/rest/email-message/send?access-token=<TOKEN>
{
  "templateId": 977,
  "type": 1,
  "email": "[email protected]",
  "playerId": "2023022617000",
  "providerId": 17,
  "subject": "Hi, {{name}}",
  "internalName": "welcome-series-step-1",
  "externalVariables": {
    "name": "John"
  }
}

  • templateId — ID of the template to use (created via API or the InTarget email builder); alternatively, pass htmlContent with the raw HTML body directly in the request instead of referencing a template — required if htmlContent is not provided

  • type — email type — optional

    • 1 — promotional (default)

    • 2 — transactional

  • email — recipient email address — required

  • playerId — player ID — optional

  • providerId — sender provider ID; contact support if you need to send from multiple addresses or domains — optional

  • subject — email subject line; supports variables like {{name}} — required

  • internalName — your own label for this send, used to group sends together in the statistics endpoint — optional

  • externalVariables — key-value pairs for any custom variables used in the template or subject — optional

Response:

{   "data": true }

If you include playerId in the request, you can use InTarget's standard player variables — such as {{name}} or {{email}} — directly in both the subject and the template content, without passing them through externalVariables.

Sending Statistics

GET https://api.intarget.app/rest/email-message/statistics?from=2023-11-08%2000:00:00&to=2023-11-09%2000:00:00&templateId=977&access-token=<TOKEN>

Response:

{
  "sent": 10,
  "delivered": 9,
  "opened": 7,
  "clicked": 3,
  "bounced": 1,
  "complaint": 0,
  "rejected": 0,
  "unsubscribed": 0,
  "failed": 0,
  "temporaryFailed": 0,
  "skipped": 0
}

Filter by internalName

If you pass internalName when sending, you can pull statistics for that name instead of filtering by template.

GET https://api.intarget.app/rest/email-message/statistics?internalName=welcome-series-step-1&access-token=<TOKEN>

This is useful when one template is reused across several scenarios, or when one scenario is sent from more than one template — the name is what ties the sends together.

Template Translations

Use the translation endpoints to manage localized versions of your email templates. Each translation is tied to a template ID and a language ID.

Translations only apply to emails sent with a playerId. InTarget uses the language set in the player's profile to determine which translation to deliver.

Get Available Languages

Returns the list of languages supported for translations in your account.

GET https://api.intarget.app/rest/email-template-translation/get-languages?access-token=<TOKEN>

Add a Translation

POST https://api.intarget.app/rest/email-template-translation/add?access-token=<TOKEN>
{
  "targetId": 29,
  "languageId": 2,
  "fields": {
    "content": "<html><body>Translated content {{ unsubscribeUrl }}</body></html>",
    "subject": "Translated subject"
  }
}

  • targetId — the template ID — required

  • languageId — the language ID from the get-languages response — required

  • fields.content — translated HTML content; must include {{ unsubscribeUrl }} — required

Response:

{
    "data": true
}

Update a Translation

POST https://api.intarget.app/rest/email-template-translation/update?access-token=<TOKEN>
{
  "targetId": 29,
  "languageId": 2,
  "fields": {
    "content": "<html><body>Updated translation {{ unsubscribeUrl }}</body></html>",
    "subject": "Updated translated subject"
  }
}

Fields are the same as for adding a translation. This replaces the existing translation for the given template and language combination.

Delete a Translation

POST https://api.intarget.app/rest/email-template-translation/delete?access-token=<TOKEN>
{
  "targetId": 29,
  "languageId": 2
}

  • targetId — the template ID — required

  • languageId — the language ID to remove — required

Related Articles
Did this answer your question?