Transactional API

If you do not use one of the standard providers that Didomi integrates with, Didomi can use a generic HTTP request to notify you that an email needs to be sent.


API request

Didomi sends a POST request to an API endpoint that you manage. When receiving that POST request, your API should send the email described by Didomi.

The body of the request is a JSON-encoded message that contains the information to send the email. Example:

Authorization: Bearer <...>
"organization_user_id": "[email protected]",
"template_id": "validation-double-optin",
"context": {
"validation_approve_url": ""

The body of the POST request contains the following properties:




Organization user ID. This can be an email address or any organization user ID that can be converted to an email address on your side.


ID of template to use for sending the email. Possible values are documented in our Templates documentation.


An object containing context parameters to build the email content from the template. This includes information on the event, approval URLs, etc. See our Templates documentation for more information.


OAuth Access Token

Requests sent to your API endpoint can be authenticated via OAuth Client Credentials grant.

The Didomi servers will authenticate against your OAuth authorization server with a Client ID and a Client Secret that you provide to obtain an Access Token.

Didomi will then call your API endpoint for sending emails with the Access Token provided in the Authorization header as a Bearer token.

IP address

API calls from Didomi will originate from the IP . You must whitelist that IP to allow traffic from it for OAuth requests and emails to be sent.


Didomi needs the following configuration items to set up the connection with your API endpoint:




API endpoint

The URL where HTTP requests must be sent to send emails


OAuth Client ID

ID of the OAuth client to use for Client Credentials grant


OAuth Client Secret

Secret of the OAuth client to use for Client Credentials grant


The configuration of the Transactional API connector cannot be done in the Didomi Console at the moment. Please reach out to Support to get your connector configured and provide the elements listed above.