Requirements

• If you want to send OTPs via the Email channel, you need to have a valid balance in your account to send OTPs, even when you’re testing it out. For SMS and Voice OTPs, you can use your test credits.

• To send via Email, you'll need to have an Email channel configured in MessageBird.

• Test your Email channel before going live. The first ones you send will typically end up in the recipient's spam folder during the first 24 hours while the IP is warmed up.

Creating a Verify object to send an OTP via SMS or Voice

1. Add your access key.

2. Make a post request to the https://rest.messagebird.com/verify.

3. Add your “from” number in the `originator` field. This is the number from which the SMS or the call is made.

4. Add the recipient number in the `recipient` field. This is the number that receives the OTP code

5. Set type parameter to `sms`, `flash` or `tts` according to the channel you’d like to send the OTP.

6. Set the validity of the code in seconds in the `timeout` parameter. The default timeout is 30 secs.

7. Set the length of the OTP code in the `tokenLength` field.

8. The default OTP length is 6 digits, you can configure it to be anywhere between 6 and 10 digits.

Example request:

{
"recipient":"[phone]",
"originator":"Verify OTP",
"Reference":"",
"type":"sms",
"template":"This is a test message from the MessageBird Verify API. Your code is *%token*",
"dataCoding":"",
"timeout":"30",
"tokenLength":"6"
}

Creating a Verify object to send an OTP via Email

1. Add your access key.

2. Make a post request to the https://rest.messagebird.com/verify.

3. Use the domain registered in the Email channel that is configured in the MessageBird Dashboard account. To do so, follow these steps.

4. Add the sender email address in the `originator` field. This is the domain that needs to be registered in the MessageBird dashboard. The name of the sender is optional.

5. Add the recipient email address in the `recipient` field. The name of the recipient is optional

6. Add the `subject` line of the Email message. By default, it is “Your OTP token” but can be configured to something different.

7. Set type parameter to `email`.

8. The default timeout is 30 secs for Verify, we recommend that you set this for a bit longer when setting up email.

9. The default OTP length is 6 digits, you can configure it to be anywhere between 6 and 10 digits.

Example request:

{
"recipient":"Sam Smith <[e-mail]>",
"originator":"Your company name<[e-mail]>",
"Reference":"",
“subject”: “”,
"type":"email",
"template":"This is a test message from the MessageBird Verify API. Your code is *%token*",
"dataCoding":"",
"timeout":"300",
"tokenLength":"6"
}

Check the status of the Verify object

To check both the Verify object and the Email object, you can make GET requests to the href links. For example: https://rest.messagebird.com/verify/messages/email/534256907df746e08029bf7ecb4841d8

The Messages href link is always different for each type of message.

The email statuses are as follows:

1. ‘Queued’.

2. Once sent to the Email API, it changes to ‘Accepted’.

3. Once sent from the Email API, it changes to ‘Sent’.

Check the status of the OTP

To prove that the token has been used, you can make a GET request to https://rest.messagebird.com/verify/{verifyID}%token={tokenID}

For example:

https://rest.messagebird.com/verify/82da0bf13e2d4f8dbda850aea2366dc1?token=490961

The OTP (also referred to as the Verify token) can be used (checked) only once. If there is a mistake from the user when inserting the token or in the API request, it will be deactivated and won't work anymore. It will be necessary to create another Verify request in this situation, which will generate a new OTP code.