Provisioning
V5 API endpoints are provisioned via Settings > Integrations. Administrator access to Taguchi is required to provision
new authentication methods, while Integration - Manage access is required to manage the API endpoints themselves.
Endpoints support the following authentication methods:
- Unauthenticated (e.g. for publicly-accessible web forms): supports subscriber profile create or update operations, event logging, and message delivery.
- Token: uses a static API token for authentication. The API token must be created Settings > Credentials area of the UI.
- JSON Web Token (JWT) with pre-shared key: uses symmetric cryptography (HS256) based on a pre-shared key to validate an access token provided by the API client. The pre-shared key must be created in the Settings > Credentials area of the UI.
- JWT with public key: uses asymmetric cryptography (RS256) based on a public/private keypair to validate an access token provided by the API client. The keypair is generated on a client system and the public key must be uploaded to the Settings > Credentials area of the UI.
Once the endpoint credentials have been configured, the endpoint integration must be created using the "V5 API Endpoint (Authenticated)" or "V5 API Endpoint (Unauthenticated)" types.
Authentication
All API requests must be made over HTTPS. The authentication requirements depend on the type of API endpoint created.
The base URL structure should be as follows:
https://{server}.taguchimail.com/apiv5_auth/{environment}/{endpoint-id}/subscriber
The {server}
used in requests is typically edm2.taguchimail.com
, but can vary if a custom domain has been configured for the server.
The {environment}
is either prod
for production requests, or test
for test requests. Until the API endpoint is activated via the blue "Activate" button, only test requests are permitted. Test requests will be processed in the same way as production requests, but will not modify data or send messages.
The {endpoint-id}
is a UUID generated once the integration is saved for the first time. Once saved, the integration's base URL will be shown in the "Endpoint URL" field, and an OpenAPI specification will be made available to download.
If in doubt, contact Taguchi Support.
Token authentication
To authenticate using a static token ("API token" credential type), use HTTP Bearer Authorization by sending the token in the following header in the HTTPS request:
Authorization: Bearer <token>
The token can optionally be transmitted in Base64-encoded form. Authentication failures will be indicated by a 403 error code.
JSON Web Token authentication
To authenticate using a JSON Web Token (JWT), you must either configure a symmetric ("API secret key") or asymmetric ("API public key") cryptography credential.
If using symmetric cryptography, the key you enter in the credential must be the same as you use to generate the JWT signature in your API client, and this key must be kept secret as exposing it will allow others to generate valid signatures. This type of credential must be used with the HS256 JWT signature algorithm.
If using asymmetric cryptography, you will generate an RSA public/private keypair, and store the private key somewhere accessible to your API client. The public key is provided to Taguchi, and is not required to be kept secret as it can only be used to validate signatures, not to create them. This type of credential must be used with the RS256 JWT signature algorithm.
Aside from a valid signature, Taguchi requires that the JWT include a "sub"
(subject) field value matching the API integration token. This ensures that signatures generated for one API integration cannot be re-used on another.
Taguchi recommends that JWTs be generated with an "exp"
(expiration) field value between 60 seconds and 10 minutes in the future, to limit abuse of leaked tokens. Note that Taguchi applies a 60 second grace period to expiration timestamps to account for clock skew and proxy delays.
For more information about JWTs, refer here.
Once generated and signed, the JWT must be included in the Authoriation header in the HTTPS request:
Authorization: Bearer <token>
Error Handling
Taguchi uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was missed), and codes in the 5xx range indicate an error with Taguchi's servers (these are rare).
Response Code |
Status |
200 - OK |
Everything working as expected. |
204 - No Content |
No content found/returned. |
400 - Bad Request |
The request was not accepted, often due to missing a required parameter, or invalid JSON serialization or structure |
403 - Forbidden |
No valid authentication or token provided. |
404 - Not Found |
The requested resource doesn't exist. |
405 - Method Not Allowed |
The resource type is not supported by the request. |
406 - Not Acceptable |
The requested output format is not supported. |
500, 502, 503, 504 Server Errors |
Something went wrong on Taguchi's end. (These are rare.) |
Profile uniqueness
Taguchi supports different types of uniqueness and identity constraint on subscriber profiles. It is important to ensure the uniqueness constraints being used by your API endpoints align with other data sources such as batch file loads or UI uploads.
The following fields are supported as unique identifiers:
- Taguchi ID: this field is generated by Taguchi and always uniquely identifies a subscriber profile;
- External ID (known as
ref
in code): this is a string value which can contain a UUID or other form of identifier generated by systems under your control;
- Email + phone: this compares both the customer's lowercase email address and the value of the phone field;
- Email: this field contains the customer email address, converted to lowercase for the purpose of assessing uniqueness;
- Phone: this field contains the customer's phone number.
When an API endpoint has been configured to use one of the above identifiers, all requests to that endpoint must use identifiers that match this configuration. In the case of an action that does not retrieve data and will not create a subscriber profile (for example, a Message Send action), Taguchi will also accept the SHA256 hash of the email address or the phone number in place of the actual email address or phone number.